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
//
// 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 service
import (
"cmp"
"context"
"encoding/json"
"errors"
"fmt"
"maps"
"ragflow/internal/permission"
"ragflow/internal/service/file"
"reflect"
"slices"
"sort"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/cloudwego/eino/compose"
"go.uber.org/zap"
"gorm.io/gorm"
"ragflow/internal/agent/canvas"
"ragflow/internal/agent/component"
"ragflow/internal/agent/runtime"
agentsandbox "ragflow/internal/agent/sandbox"
agenttool "ragflow/internal/agent/tool"
"ragflow/internal/common"
"ragflow/internal/dao"
"ragflow/internal/entity"
permissionresponse "ragflow/internal/permission/response"
"ragflow/internal/tokenizer"
"ragflow/internal/utility"
dslpkg "ragflow/internal/agent/dsl"
)
// webhookPayloadKey is the unexported context key RunAgent reads to
// inject root["webhook_payload"]. Only the AgentService.RunAgentWithWebhook
// public wrapper sets it; the chat / agent-run paths leave it absent so
// existing callers see no behavior change.
//
// We deliberately do NOT surface the payload as a new RunAgent parameter
// — keeping the public signature stable means existing tests
// (agent_run_e2e_test.go, agent_wait_for_user_test.go) keep compiling.
type webhookPayloadKey struct{}
// LoadCanvasByID is the read-side counterpart of loadCanvasForUser that
// the webhook handler uses. It deliberately returns the raw DAO/service
// error (no error-code mapping) because the webhook envelope is 102
// "Canvas not found." while the chat/run envelope is 103 "Make sure you
// have permission..." — the choice must stay at the HTTP layer where
// each handler knows its own spec.
//
// Mirrors python: api/apps/restful_apis/agent_api.py:1570
// (`UserCanvasService.get_by_id(agent_id)`), with the same IDOR guard
// the chat handler uses.
func (s *AgentService) LoadCanvasByID(ctx context.Context, canvasID string) (*entity.UserCanvas, error) {
return s.loadCanvasForUser(ctx, canvasID, permission.OperationRead)
}
// RunAgentWithWebhook is a thin wrapper over RunAgent that attaches the
// webhook payload to the runner root so the Begin component can surface
// it as state.Sys["webhook_payload"] for downstream components.
//
// The payload is intentionally passed via context value (rather than a new
// RunAgent parameter) to keep the public RunAgent signature stable for
// the existing chat tests.
//
// Mirrors python: api/apps/restful_apis/agent_api.py:2125
// (`canvas.run(..., webhook_payload=clean_request)`).
func (s *AgentService) RunAgentWithWebhook(
ctx context.Context, canvasID string, payload map[string]any,
) (<-chan canvas.RunEvent, error) {
if payload != nil {
ctx = context.WithValue(ctx, webhookPayloadKey{}, payload)
}
return s.RunAgent(ctx, canvasID, AgentSessionIDFromContext(ctx), "", "", nil)
}
type agentSessionIDContextKey struct{}
type agentChannelNameContextKey struct{}
type openAICompatMessagesContextKey struct{}
// WithAgentSessionID lets an HTTP boundary allocate the session identity while
// keeping session-record persistence inside AgentService.RunAgent.
func WithAgentSessionID(ctx context.Context, sessionID string) context.Context {
return context.WithValue(ctx, agentSessionIDContextKey{}, sessionID)
}
// AgentSessionIDFromContext returns an HTTP-assigned session identity, if any.
func AgentSessionIDFromContext(ctx context.Context) string {
if ctx == nil {
return ""
}
sessionID, _ := ctx.Value(agentSessionIDContextKey{}).(string)
return sessionID
}
// withAgentChannelName lets a chat-channel boundary record the channel name so
// the session RunAgent creates carries it in its display name.
func withAgentChannelName(ctx context.Context, channelName string) context.Context {
name := strings.TrimSpace(channelName)
if name == "" {
return ctx
}
return context.WithValue(ctx, agentChannelNameContextKey{}, name)
}
func agentChannelNameFromContext(ctx context.Context) string {
if ctx == nil {
return ""
}
name, _ := ctx.Value(agentChannelNameContextKey{}).(string)
return name
}
// WithOpenAICompatMessages attaches the complete OpenAI messages list to an
// agent run without changing RunAgent's public argument list. The latest user
// message remains the run input; the service uses the earlier messages to seed
// the workflow history.
func WithOpenAICompatMessages(ctx context.Context, messages []map[string]interface{}) context.Context {
if len(messages) == 0 {
return ctx
}
copied := make([]map[string]interface{}, len(messages))
for i, message := range messages {
copied[i] = make(map[string]interface{}, len(message))
for key, value := range message {
copied[i][key] = value
}
}
return context.WithValue(ctx, openAICompatMessagesContextKey{}, copied)
}
func openAICompatMessagesFromContext(ctx context.Context) []map[string]interface{} {
if ctx == nil {
return nil
}
messages, _ := ctx.Value(openAICompatMessagesContextKey{}).([]map[string]interface{})
return messages
}
func emitAgentMessageEvents(emit func(string, string), answer, thinking string, reference any) {
for _, ev := range buildAgentMessageEvents(answer, thinking, reference) {
data, _ := json.Marshal(ev)
emit("message", string(data))
}
}
type agentMessageDeltaEmitter struct {
emit func(string, string)
thinkState *ThinkStreamState
inThinking bool
explicitReasoning bool
emitted bool
}
func newAgentMessageDeltaEmitter(emit func(string, string)) *agentMessageDeltaEmitter {
return &agentMessageDeltaEmitter{
emit: emit,
thinkState: &ThinkStreamState{},
}
}
func (e *agentMessageDeltaEmitter) emitEvent(ev canvas.MessageEvent) {
emitAgentMessageEvent(e.emit, ev)
e.emitted = true
}
func (e *agentMessageDeltaEmitter) startThinking() {
if e.inThinking {
return
}
e.emitEvent(canvas.MessageEvent{StartToThink: true})
e.inThinking = true
}
func (e *agentMessageDeltaEmitter) endThinking() {
if !e.inThinking {
return
}
e.emitEvent(canvas.MessageEvent{EndToThink: true})
e.inThinking = false
}
func (e *agentMessageDeltaEmitter) emitThinkDeltas(deltas []ThinkDelta) {
for _, d := range deltas {
switch {
case d.Kind == ThinkDeltaMarker && d.Value == thinkOpen:
e.startThinking()
case d.Kind == ThinkDeltaMarker && d.Value == thinkClose:
e.endThinking()
case d.Kind == ThinkDeltaText && d.Value != "":
e.emitEvent(canvas.MessageEvent{Content: d.Value})
}
}
}
func (e *agentMessageDeltaEmitter) Emit(contentDelta, thinkingDelta string) {
if thinkingDelta != "" {
e.startThinking()
e.explicitReasoning = true
e.emitEvent(canvas.MessageEvent{Content: thinkingDelta})
}
if contentDelta == "" {
return
}
if e.explicitReasoning {
e.endThinking()
e.explicitReasoning = false
}
e.emitThinkDeltas(NextThinkDelta(e.thinkState, contentDelta, 0))
}
func (e *agentMessageDeltaEmitter) Finalize() bool {
before := e.emitted
e.emitThinkDeltas(FlushRemaining(e.thinkState))
if e.explicitReasoning || e.inThinking {
e.endThinking()
e.explicitReasoning = false
}
return e.emitted && !before
}
func (e *agentMessageDeltaEmitter) Reset() {
e.thinkState = &ThinkStreamState{}
e.inThinking = false
e.explicitReasoning = false
e.emitted = false
}
func makeAgentMessageDeltaEmitter(emit func(string, string)) func(string, string) {
return newAgentMessageDeltaEmitter(emit).Emit
}
func makeAgentMessageDeltaEmitterWithFinalizer(emit func(string, string)) (func(string, string), func() bool, func()) {
emitter := newAgentMessageDeltaEmitter(emit)
return emitter.Emit, emitter.Finalize, emitter.Reset
}
func emitAgentMessageEvent(emit func(string, string), ev canvas.MessageEvent) {
data, _ := json.Marshal(ev)
emit("message", string(data))
}
func buildAgentMessageEvents(answer, thinking string, reference any) []canvas.MessageEvent {
answer, thinking = splitInlineThink(answer, thinking)
if thinking == "" {
return []canvas.MessageEvent{{
Content: answer,
Reference: reference,
}}
}
events := []canvas.MessageEvent{{StartToThink: true}}
for _, chunk := range splitMessageContent(thinking) {
events = append(events, canvas.MessageEvent{Content: chunk})
}
events = append(events, canvas.MessageEvent{EndToThink: true})
for _, chunk := range splitMessageContent(answer) {
events = append(events, canvas.MessageEvent{Content: chunk})
}
return events
}
func splitInlineThink(answer, thinking string) (string, string) {
if thinking != "" {
return answer, thinking
}
const startTag = "<think>"
const endTag = "</think>"
start := strings.Index(answer, startTag)
if start < 0 {
return answer, thinking
}
afterStart := start + len(startTag)
endRel := strings.Index(answer[afterStart:], endTag)
if endRel < 0 {
return answer, thinking
}
end := afterStart + endRel
thinking = answer[afterStart:end]
answer = answer[:start] + answer[end+len(endTag):]
answer = strings.TrimLeft(answer, "\r\n")
return answer, thinking
}
// agentSessionMessageContent mirrors how Python's canvas_service.completion
// accumulates the persisted assistant message: reasoning streams first,
// bracketed by start_to_think/end_to_think markers, so the stored content
// keeps the thinking segment wrapped in <think> tags. The chat UI refetches
// the session message list after streaming and needs those tags for
// MarkdownContent to render the "thought" section (chat.thought).
func agentSessionMessageContent(answer, thinking string) string {
if thinking == "" {
return answer
}
return "<think>" + thinking + "</think>" + answer
}
func splitMessageContent(content string) []string {
if content == "" {
return nil
}
const maxRunes = 24
runes := []rune(content)
chunks := make([]string, 0, (len(runes)+maxRunes-1)/maxRunes)
for len(runes) > 0 {
n := maxRunes
if len(runes) < n {
n = len(runes)
}
chunks = append(chunks, string(runes[:n]))
runes = runes[n:]
}
return chunks
}
// ErrAgentNotOwner is returned when a caller cannot delete an agent canvas.
// The handler maps both missing and inaccessible canvases to the same
// response to avoid revealing resource existence.
var ErrAgentNotOwner = errors.New("agent not owned by user")
// ErrAgentStorageError identifies internal Agent service failures such as
// database connectivity, schema drift, or persistence errors. Synchronous
// callers map this sentinel to a sanitized 500 response; failures raised after
// streaming starts are wrapped with canvas.NewInternalRunError so Runner emits
// the same safe message in its terminal event.
var ErrAgentStorageError = errors.New("agent storage error")
// AgentService agent service
type AgentService struct {
canvasDAO *dao.UserCanvasDAO
canvasTemplateDAO *dao.CanvasTemplateDAO
userDAO *dao.UserDAO
userTenantDAO *dao.UserTenantDAO
versionDAO *dao.UserCanvasVersionDAO
api4ConversationDAO *dao.API4ConversationDAO
compilationTemplateGroupDAO *dao.CompilationTemplateGroupDAO
compilationTemplateDAO *dao.CompilationTemplateDAO
// driver is the per-process runner that drives canvas
// invocations and produces SSE events. V1 persistence is
// in-memory; a follow-up phase moves to Redis per plan §4.9.
runner *canvas.Runner
// Phase 4.4 V2 — Kvrocks-backed run infrastructure. nil = in-memory
// / no-tracking (test path, current production boot path until
// cmd/server_main.go wires them in v3.6.0).
//
// checkpointStore + stateSerializer feed canvas.WithCheckPointStore
// / canvas.WithStateSerializer so every Compile's check-point
// payload and CanvasState snapshot round-trip to Redis.
checkpointStore canvas.CheckPointStore
stateSerializer canvas.StateSerializer
// runTracker records per-run lifecycle (Start / MarkSucceeded /
// MarkFailed / MarkCancelled) to Redis hash "agent:run:{id}".
runTracker *canvas.RunTracker
runMu sync.Mutex
activeSessions map[string]*activeAgentRun
}
type activeAgentRun struct {
userID string
canvasID string
sessionID string
leaseToken string
cancelRun context.CancelFunc
cancelRequested atomic.Bool
}
func (r *activeAgentRun) requestCancel() {
if r == nil {
return
}
r.cancelRequested.Store(true)
if r.cancelRun != nil {
r.cancelRun()
}
}
// NewAgentService create agent service
func NewAgentService() *AgentService {
return NewAgentServiceWithOptions(nil, nil, nil)
}
// NewAgentServiceWithOptions is the production constructor that
// injects the Kvrocks-backed run infrastructure. The zero-arg
// NewAgentService() remains as a thin wrapper that calls this with
// all-nil options so existing call sites (cmd/server_main.go,
// handler tests, agent_test.go) keep compiling.
//
// Phase 4.4 V2: production boot wiring is deferred to v3.6.0; until
// then, tests can construct AgentService instances with mocked
// stores/tracker to exercise the real Compile/Invoke path without
// requiring Redis.
func NewAgentServiceWithOptions(
cp canvas.CheckPointStore,
ser canvas.StateSerializer,
rt *canvas.RunTracker,
) *AgentService {
if stub, ok := agenttool.GetSandboxClient().(interface{ IsStubSandboxClient() bool }); ok && stub.IsStubSandboxClient() {
agenttool.SetSandboxClient(agentsandbox.NewManagerClient())
}
return &AgentService{
canvasDAO: dao.NewUserCanvasDAO(),
canvasTemplateDAO: dao.NewCanvasTemplateDAO(),
userDAO: dao.NewUserDAO(),
userTenantDAO: dao.NewUserTenantDAO(),
versionDAO: dao.NewUserCanvasVersionDAO(),
api4ConversationDAO: dao.NewAPI4ConversationDAO(),
compilationTemplateGroupDAO: dao.NewCompilationTemplateGroupDAO(),
compilationTemplateDAO: dao.NewCompilationTemplateDAO(),
runner: canvas.NewRunner(),
activeSessions: make(map[string]*activeAgentRun),
checkpointStore: cp,
stateSerializer: ser,
runTracker: rt,
}
}
// ListTemplates returns every canvas template. Mirrors Python
// agent_api.list_agent_template, which iterates CanvasTemplateService.get_all()
// and serialises each row.
func (s *AgentService) ListTemplates(ctx context.Context) ([]*entity.CanvasTemplate, error) {
return s.canvasTemplateDAO.GetAll(ctx, dao.DB)
}
// AgentItem is one entry in the list response.
type AgentItem struct {
ID string `json:"id"`
Avatar *string `json:"avatar,omitempty"`
Title *string `json:"title,omitempty"`
Description *string `json:"description,omitempty"`
Permission string `json:"permission"`
UserID string `json:"user_id"`
TenantID string `json:"tenant_id"`
Nickname string `json:"nickname"`
TenantAvatar *string `json:"tenant_avatar,omitempty"`
Tags string `json:"tags"`
CanvasType *string `json:"canvas_type,omitempty"`
CanvasCategory string `json:"canvas_category"`
OperatorPermission int32 `json:"operator_permission,omitempty"`
CreateTime *int64 `json:"create_time,omitempty"`
UpdateTime *int64 `json:"update_time,omitempty"`
ReleaseTime *int64 `json:"release_time,omitempty"`
// Type discriminates agent vs compilation-template-group items in the merged
// /agents response. It is set only for merged items (agent => "agent").
Type string `json:"type,omitempty"`
}
// ListAgentsResponse is the response body for GET /api/v1/agents. Canvas holds
// pre-marshalled JSON items because a canvas entry is either an agent (AgentItem
// shape) or a compilation template group (group shape with a "type" of
// "compilation_template_group"); a single typed slice cannot express both.
type ListAgentsResponse struct {
Canvas []json.RawMessage `json:"canvas"`
Total int64 `json:"total"`
}
// AgentItemType discriminates the two kinds of canvas items in the merged
// /agents response, mirroring Python _COMPILATION_TEMPLATE_GROUP_CATEGORY and
// the frontend AgentListItem union.
const (
AgentItemTypeAgent = "agent"
AgentItemTypeGroup = CompilationTemplateGroupCategory // "compilation_template_group"
)
// CompilationTemplateGroupCategory is the synthetic canvas_category the
// frontend uses to filter compilation template groups through the merged
// /agents endpoint. Mirrors Python _COMPILATION_TEMPLATE_GROUP_CATEGORY.
const CompilationTemplateGroupCategory = "compilation_template_group"
// AgentOwnerFilter is one owner option in the agents filter response.
type AgentOwnerFilter struct {
ID string `json:"id"`
Label string `json:"label"`
Count int64 `json:"count"`
}
// AgentCategoryFilter is one canvas_category option in the agents filter
// response.
type AgentCategoryFilter struct {
ID string `json:"id"`
Count int64 `json:"count"`
}
// AgentFiltersResponse is the response body for
// GET /api/v1/agents?type=filter.
type AgentFiltersResponse struct {
Filter struct {
Owner []AgentOwnerFilter `json:"owner"`
CanvasCategory []AgentCategoryFilter `json:"canvas_category"`
} `json:"filter"`
Total int64 `json:"total"`
}
// ListAgentFilters returns the owner/category aggregations backing the
// agents page filter bar. Mirrors the ?type=filter branch of Python
// agent_api.list_agents. A non-empty canvasCategory scopes the owner counts
// to one tab: canvas categories aggregate only that category's canvases,
// while CompilationTemplateGroupCategory reports the tenant's groups.
func (s *AgentService) ListAgentFilters(ctx context.Context, canvasCategory string) (*AgentFiltersResponse, common.ErrorCode, error) {
userID := permission.UserIDFromContext(ctx)
if canvasCategory == CompilationTemplateGroupCategory {
return s.listCompilationGroupFilters(ctx)
}
canvasScope, err := permission.NewDatabaseChecker(dao.DB).Scope(ctx, permission.ScopeQuery{
Kind: permission.ResourceKindCanvas,
Operation: permission.OperationRead,
})
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to scope accessible canvases: %w", err)
}
canvasIDs := canvasScope.ResourceIDs
if canvasScope.Mode == permission.ScopeNone {
canvasIDs = []string{}
}
owners, err := s.canvasDAO.GetOwnerFilterByCanvasIDs(ctx, dao.DB, canvasIDs, canvasCategory)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to aggregate agent owners: %w", err)
}
categories, err := s.canvasDAO.GetCategoryFilterByCanvasIDs(ctx, dao.DB, canvasIDs)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to aggregate agent categories: %w", err)
}
// Compilation groups only belong in the unscoped aggregation; a scoped
// canvas-category request never includes them.
groupCount := int64(0)
if canvasCategory == "" {
groupCount, err = s.compilationTemplateGroupDAO.CountSavedByTenant(ctx, dao.DB, userID)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to count compilation template groups: %w", err)
}
}
ownerFilters := make([]AgentOwnerFilter, 0, len(owners)+1)
for _, o := range owners {
label := o.ID
if o.Label != nil && *o.Label != "" {
label = *o.Label
}
ownerFilters = append(ownerFilters, AgentOwnerFilter{ID: o.ID, Label: label, Count: o.Count})
}
if groupCount > 0 {
idx := -1
for i := range ownerFilters {
if ownerFilters[i].ID == userID {
idx = i
break
}
}
if idx >= 0 {
ownerFilters[idx].Count += groupCount
} else {
nickname, nerr := s.userDAO.GetNicknameByID(ctx, dao.DB, userID)
if nerr != nil {
nickname = ""
}
ownerFilters = append(ownerFilters, AgentOwnerFilter{ID: userID, Label: nickname, Count: groupCount})
}
}
categoryFilters := make([]AgentCategoryFilter, 0, len(categories)+1)
for _, c := range categories {
categoryFilters = append(categoryFilters, AgentCategoryFilter{ID: c.ID, Count: c.Count})
}
if groupCount > 0 {
categoryFilters = append(categoryFilters, AgentCategoryFilter{ID: CompilationTemplateGroupCategory, Count: groupCount})
}
var total int64
for _, o := range ownerFilters {
total += o.Count
}
resp := &AgentFiltersResponse{Total: total}
resp.Filter.Owner = ownerFilters
resp.Filter.CanvasCategory = categoryFilters
return resp, common.CodeSuccess, nil
}
// listCompilationGroupFilters reports the tenant's compilation template groups
// as the only owner/category option: groups are tenant-owned and carry neither
// canvas categories nor per-canvas owners.
func (s *AgentService) listCompilationGroupFilters(ctx context.Context) (*AgentFiltersResponse, common.ErrorCode, error) {
userID := permission.UserIDFromContext(ctx)
groupCount, err := s.compilationTemplateGroupDAO.CountSavedByTenant(ctx, dao.DB, userID)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to count compilation template groups: %w", err)
}
resp := &AgentFiltersResponse{Total: groupCount}
resp.Filter.Owner = []AgentOwnerFilter{}
resp.Filter.CanvasCategory = []AgentCategoryFilter{}
if groupCount > 0 {
nickname, nerr := s.userDAO.GetNicknameByID(ctx, dao.DB, userID)
if nerr != nil {
nickname = ""
}
resp.Filter.Owner = append(resp.Filter.Owner, AgentOwnerFilter{ID: userID, Label: nickname, Count: groupCount})
resp.Filter.CanvasCategory = append(resp.Filter.CanvasCategory, AgentCategoryFilter{ID: CompilationTemplateGroupCategory, Count: groupCount})
}
return resp, common.CodeSuccess, nil
}
type AgentTagCount struct {
Tag string `json:"tag"`
Count int `json:"count"`
}
func toAgentItem(c *dao.UserCanvasListItem) *AgentItem {
nickname := ""
if c.Nickname != nil {
nickname = *c.Nickname
}
if nickname == "" {
nickname = c.TenantID
}
return &AgentItem{
ID: c.ID,
Avatar: c.Avatar,
Title: c.Title,
Description: c.Description,
Permission: c.Permission,
UserID: c.UserID,
TenantID: c.TenantID,
Nickname: nickname,
TenantAvatar: c.TenantAvatar,
CanvasType: c.CanvasType,
CanvasCategory: c.CanvasCategory,
OperatorPermission: c.OperatorPermission,
Tags: c.Tags,
CreateTime: c.CreateTime,
UpdateTime: c.UpdateTime,
}
}
// ListAgents returns agent canvases visible to the authenticated caller.
// Mirrors Python agent_api.list_agents — validates owner_ids against joined tenants,
// then delegates to the DAO.
func (s *AgentService) ListAgents(ctx context.Context, keywords string, page, pageSize int, terms []dao.OrderTerm, ownerIDs []string, canvasCategory, canvasType string, tags []string) (*ListAgentsResponse, common.ErrorCode, error) {
userID := permission.UserIDFromContext(ctx)
checker := permission.NewDatabaseChecker(dao.DB)
canvasScope, err := checker.Scope(ctx, permission.ScopeQuery{
Kind: permission.ResourceKindCanvas,
Operation: permission.OperationRead,
})
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to scope accessible canvases: %w", err)
}
canvasIDs := canvasScope.ResourceIDs
if canvasScope.Mode == permission.ScopeNone {
canvasIDs = []string{}
}
if len(ownerIDs) > 0 {
for _, id := range ownerIDs {
if id == userID {
continue
}
if err := checker.CheckTenant(ctx, id, permission.TenantMember); err != nil {
if errors.Is(err, permission.ErrMembershipNotFound) {
return nil, common.CodeOperatingError, fmt.Errorf("only authorized owner_ids can be queried")
}
return nil, common.CodeServerError, fmt.Errorf("validate agent owner_id: %w", err)
}
}
}
effectiveOwnerIDs := ownerIDs
// A canvas entry is either an agent (user_canvas) or a compilation template
// group. Python splits canvas_category on commas and, when the tenant is the
// sole effective owner, merges the caller's template groups into the list.
categories := splitCategoryList(canvasCategory)
wantsGroups := sliceContains(categories, CompilationTemplateGroupCategory)
agentCategories := filterCategory(categories, CompilationTemplateGroupCategory)
// Merge mode mirrors Python: no category, no canvas_type, no tags -> the
// caller's template groups are interleaved with agents by update_time.
mergeMode := len(categories) == 0 && canvasType == "" && len(tags) == 0
// Groups-only mode: canvas_category is exactly ["compilation_template_group"].
// Template groups are always the caller's own, so they are only visible when
// the caller is an effective owner; otherwise (e.g. owner_ids names another
// user) return an empty list (review Major).
if len(categories) == 1 && wantsGroups {
if len(ownerIDs) > 0 && !sliceContains(effectiveOwnerIDs, userID) {
return &ListAgentsResponse{Canvas: []json.RawMessage{}, Total: 0}, common.CodeSuccess, nil
}
return s.listAgentsGroupsOnly(ctx, keywords, terms, page, pageSize)
}
// Fetch agents. In merge/mixed modes we disable SQL pagination (page=0) and
// paginate in Go after interleaving with groups, matching Python.
listPage, listSize := page, pageSize
if mergeMode || (wantsGroups && len(agentCategories) > 0) {
listPage, listSize = 0, 0
}
canvases, total, err := s.canvasDAO.ListByIDs(
ctx,
dao.DB,
canvasIDs,
effectiveOwnerIDs,
listPage,
listSize,
terms,
keywords,
agentCategories,
canvasType,
tags,
)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to list agents: %w", err)
}
agentItems := make([]*AgentItem, len(canvases))
for i, c := range canvases {
access, accessErr := checker.ResolveAccess(ctx, permission.ResourceRef{
Kind: permission.ResourceKindCanvas,
ID: c.ID,
})
if accessErr != nil {
return nil, common.CodeServerError, fmt.Errorf("resolve agent permissions: %w", accessErr)
}
c.OperatorPermission = access.PermissionMask
agentItems[i] = toAgentItem(c)
}
s.attachReleaseTimes(ctx, agentItems)
// Groups are owner-only (no team sharing) and scoped to the caller, so they
// are merged only when the caller's own tenant is an effective owner
// (Python include_template_groups).
includeGroups := len(ownerIDs) == 0 || sliceContains(effectiveOwnerIDs, userID)
if includeGroups && (mergeMode || wantsGroups) {
return s.mergeAgentsAndGroups(ctx, agentItems, keywords, terms, page, pageSize)
}
raw := make([]json.RawMessage, len(agentItems))
for i, item := range agentItems {
item.Type = AgentItemTypeAgent
raw[i] = marshalAgentItem(item)
}
return &ListAgentsResponse{Canvas: raw, Total: total}, common.CodeSuccess, nil
}
// listAgentsGroupsOnly returns only the caller's compilation template groups
// (Python canvas_category == ["compilation_template_group"] branch).
func (s *AgentService) listAgentsGroupsOnly(ctx context.Context, keywords string, terms []dao.OrderTerm, page, pageSize int) (*ListAgentsResponse, common.ErrorCode, error) {
userID := permission.UserIDFromContext(ctx)
groups, err := s.compilationTemplateGroupDAO.ListSaved(ctx, dao.DB, userID, keywords, "", terms)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to list compilation template groups: %w", err)
}
total := int64(len(groups))
groups = slicePage(groups, page, pageSize)
raw := make([]json.RawMessage, 0, len(groups))
for _, g := range groups {
item, err := s.marshalMergeGroupItem(ctx, g)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to build group item: %w", err)
}
raw = append(raw, item)
}
return &ListAgentsResponse{Canvas: raw, Total: total}, common.CodeSuccess, nil
}
// mergeAgentsAndGroups combines agents and the caller's compilation template
// groups into a single list ordered by the requested timestamp, then pages in Go.
// A stable sort retains the original
// agent-before-group order when timestamps are equal.
func (s *AgentService) mergeAgentsAndGroups(ctx context.Context, agentItems []*AgentItem, keywords string, terms []dao.OrderTerm, page, pageSize int) (*ListAgentsResponse, common.ErrorCode, error) {
userID := permission.UserIDFromContext(ctx)
groups, err := s.compilationTemplateGroupDAO.ListSaved(ctx, dao.DB, userID, keywords, "", terms)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to list compilation template groups: %w", err)
}
merged := make([]mergeCanvasItem, 0, len(agentItems)+len(groups))
byCreation := len(terms) > 0 && terms[0].Column == "create_time"
for _, item := range agentItems {
item.Type = AgentItemTypeAgent
timestamp := item.UpdateTime
if byCreation {
timestamp = item.CreateTime
}
merged = append(merged, mergeCanvasItem{
item: item,
time: intValuePtr(timestamp),
})
}
for _, g := range groups {
raw, err := s.marshalMergeGroupItem(ctx, g)
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("failed to build group item: %w", err)
}
timestamp := g.UpdateTime
if byCreation {
timestamp = g.CreateTime
}
merged = append(merged, mergeCanvasItem{
raw: raw,
time: intValuePtr(timestamp),
})
}
descending := len(terms) > 0 && terms[0].Desc
slices.SortStableFunc(merged, func(a, b mergeCanvasItem) int {
if descending {
return cmp.Compare(b.time, a.time)
}
return cmp.Compare(a.time, b.time)
})
total := int64(len(merged))
merged = slicePage(merged, page, pageSize)
raw := make([]json.RawMessage, 0, len(merged))
for _, m := range merged {
if m.raw != nil {
raw = append(raw, m.raw)
} else if m.item != nil {
raw = append(raw, marshalAgentItem(m.item))
}
}
return &ListAgentsResponse{Canvas: raw, Total: total}, common.CodeSuccess, nil
}
// marshalMergeGroupItem renders a compilation template group as a merged /agents
// canvas item: the group shape (ICompilationTemplateGroup) plus the "type" and
// "title" discriminators the frontend union expects (Python _group_to_dict).
func (s *AgentService) marshalMergeGroupItem(ctx context.Context, g *entity.CompilationTemplateGroup) (json.RawMessage, error) {
children, err := s.compilationTemplateDAO.ListByGroup(ctx, dao.DB, g.ID)
if err != nil {
return nil, err
}
templates := make([]json.RawMessage, 0, len(children))
for _, c := range children {
templates = append(templates, marshalGroupTemplate(c))
}
item := map[string]interface{}{
"id": g.ID,
"name": g.Name,
"title": g.Name,
"description": derefString(g.Description),
"scope": g.Scope,
"create_time": intValuePtr(g.CreateTime),
"update_time": intValuePtr(g.UpdateTime),
"templates": templates,
"type": AgentItemTypeGroup,
}
b, err := json.Marshal(item)
if err != nil {
return nil, err
}
return b, nil
}
// mergeCanvasItem is an entry in the merged /agents list. Exactly one of item
// (an agent) or raw (a marshalled group) is set.
type mergeCanvasItem struct {
item *AgentItem
raw json.RawMessage
time int64
}
// attachReleaseTimes populates ReleaseTime for each agent item from the latest
// published version (Python UserCanvasService.get_list parity).
func (s *AgentService) attachReleaseTimes(ctx context.Context, items []*AgentItem) {
if len(items) == 0 {
return
}
canvasIDs := make([]string, 0, len(items))
for _, item := range items {
canvasIDs = append(canvasIDs, item.ID)
}
releaseTimes, err := s.versionDAO.GetLatestReleaseTimes(ctx, dao.DB, canvasIDs)
if err != nil {
return
}
for _, item := range items {
if t, ok := releaseTimes[item.ID]; ok {
item.ReleaseTime = &t
}
}
}
// marshalAgentItem renders an agent item to its JSON representation.
func marshalAgentItem(item *AgentItem) json.RawMessage {
b, err := json.Marshal(item)
if err != nil {
return json.RawMessage("null")
}
return b
}
// marshalGroupTemplate renders a compilation template child to the read-side
// shape the frontend group card expects (mirrors Python _to_saved_dict).
func marshalGroupTemplate(c *entity.CompilationTemplate) json.RawMessage {
item := map[string]interface{}{
"id": c.ID,
"name": c.Name,
"description": derefString(c.Description),
"kind": c.Kind,
"config": c.Config,
"create_time": intValuePtr(c.CreateTime),
"update_time": intValuePtr(c.UpdateTime),
}
b, err := json.Marshal(item)
if err != nil {
return json.RawMessage("null")
}
return b
}
// splitCategoryList splits a comma-separated canvas_category query into the
// non-empty categories, mirroring Python
// request.args.get("canvas_category", "").strip().split(",").
func splitCategoryList(s string) []string {
var out []string
for _, part := range strings.Split(s, ",") {
if p := strings.TrimSpace(part); p != "" {
out = append(out, p)
}
}
return out
}
// filterCategory returns the categories in src that are not equal to drop.
func filterCategory(src []string, drop string) []string {
var out []string
for _, c := range src {
if c != drop {
out = append(out, c)
}
}
return out
}
// sliceContains reports whether v is present in s.
func sliceContains[T comparable](s []T, v T) bool {
for _, e := range s {
if e == v {
return true
}
}
return false
}
// slicePage returns a shallow copy of s bounded to the requested page window.
// A page <= 0 or pageSize <= 0 returns s unchanged (caller did not ask to page).
// The page bound is checked arithmetically before computing the offset so an
// unbounded positive page/page_size can never overflow to a negative start and
// panic (review Critical).
func slicePage[T any](s []T, page, pageSize int) []T {
if page <= 0 || pageSize <= 0 || len(s) == 0 {
return s
}
// page-1 must be <= (len(s)-1)/pageSize, i.e. start must be < len(s).
if page-1 > (len(s)-1)/pageSize {
return nil
}
start := (page - 1) * pageSize
if pageSize >= len(s)-start {
return s[start:]
}
return s[start : start+pageSize]
}
// intValuePtr dereferences a *int64 to a plain int64 (0 when nil), used for the
// group/template create_time & update_time epoch fields in merged items.
func intValuePtr(p *int64) int64 {
if p == nil {
return 0
}
return *p
}
// CreateAgentRequest is the input shape for CreateAgent.
type CreateAgentRequest struct {
Title *string `json:"title,omitempty"`
Description *string `json:"description,omitempty"`
Permission string `json:"permission"`
CanvasType *string `json:"canvas_type,omitempty"`
CanvasCategory string `json:"canvas_category"`
DSL entity.JSONMap `json:"dsl,omitempty"`
}
// CreateAgent inserts a new user_canvas row. ID is assigned here.
//
// Returns the standard (T, common.ErrorCode, error) triple so the handler
// can map validation/duplicate errors to codes 101/102 without
// introducing a separate error type. Missing DSL or title and a
// duplicate title under the authenticated owner surface as specific codes.
func (s *AgentService) CreateAgent(ctx context.Context, req *CreateAgentRequest) (*entity.UserCanvas, common.ErrorCode, error) {
userID := strings.TrimSpace(permission.UserIDFromContext(ctx))
if userID == "" {
code, permissionErr := permissionresponse.Normalize(permission.ErrUnauthenticated)
return nil, code, permissionErr
}
tenantID, err := prepareAgentCreation(ctx)
if err != nil {
code, normalized := permissionresponse.Normalize(err)
return nil, code, normalized
}
if req == nil {
return nil, common.CodeArgumentError, errors.New("create agent: nil request")
}
if req.DSL == nil {
return nil, common.CodeArgumentError, errors.New("no DSL data in request")
}
if req.Title == nil || strings.TrimSpace(*req.Title) == "" {
return nil, common.CodeArgumentError, errors.New("no title in request")
}
title := strings.TrimSpace(*req.Title)
if err := common.ValidateNameRunes(title, common.NameLimit255); err != nil {
return nil, common.CodeArgumentError, fmt.Errorf("create agent: %w", err)
}
req.Title = &title
if req.Permission == "" {
req.Permission = "me"
}
if req.CanvasCategory == "" {
req.CanvasCategory = "agent_canvas"
}
uniqueTitle, err := common.UniqueName(title, common.NameLimit255, func(candidate string) (bool, error) {
return s.canvasDAO.TitleExists(ctx, dao.DB, userID, req.CanvasCategory, candidate, "")
})
if err != nil {
return nil, common.CodeServerError, fmt.Errorf("check duplicate title: %w", err)
}
title = uniqueTitle
req.Title = &title
if err := component.ValidateIntegerParameters(req.DSL); err != nil {
return nil, common.CodeArgumentError, fmt.Errorf("create agent: %w", err)
}
if err := component.ValidateDraftDynamicEntries(req.DSL); err != nil {
return nil, common.CodeArgumentError, fmt.Errorf("create agent: %w", err)
}
// Normalize legacy v1 / Go-v2 payloads to a React-Flow-shaped graph so
// the front-end can render the canvas without a migration. Idempotent;
// no-op when graph.nodes is already non-empty.
req.DSL = dslpkg.NormalizeForCanvas(req.DSL)
row := &entity.UserCanvas{
ID: common.GenerateUUID(),
UserID: userID,
TenantID: &tenantID,
Title: req.Title,
Description: req.Description,
Permission: req.Permission,
CanvasType: req.CanvasType,
CanvasCategory: req.CanvasCategory,
DSL: req.DSL,
}
if err := dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := s.canvasDAO.Create(ctx, tx, row); err != nil {
return err
}
return permission.NewDatabaseChecker(tx).GrantResourceOwner(ctx,
permission.ResourceRef{Kind: permission.ResourceKindCanvas, ID: row.ID})
}); err != nil {
if dao.IsDuplicateKeyErr(err) {
return nil, common.CodeDataError, agentTitleAlreadyExistsError(title)
}
return nil, common.CodeServerError, fmt.Errorf("create agent: %w", err)
}
return row, common.CodeSuccess, nil
}
func agentTitleAlreadyExistsError(title string) error {
return errors.New(title + " already exists.")
}
func updatedAgentTitle(canvasInstance *entity.UserCanvas, updates map[string]interface{}) (string, bool) {
if value, ok := updates["title"]; ok {
title, ok := value.(string)
if !ok {
return "", false
}
return title, true
}
if _, ok := updates["canvas_category"]; !ok {
return "", false
}
if canvasInstance.Title == nil {
return "", false
}
return *canvasInstance.Title, true
}
func updatedAgentCanvasCategory(canvasInstance *entity.UserCanvas, updates map[string]interface{}) string {
if value, ok := updates["canvas_category"]; ok {
if canvasCategory, ok := value.(string); ok {
return canvasCategory
}
}
return canvasInstance.CanvasCategory
}
// loadCanvasForUser is the shared IDOR guard used by every non-List
// canvas method. It resolves the caller's tenant set, then asks the DAO
// to load the canvas subject to the (owner OR team-in-tenant) predicate.
// On miss or access-deny it returns dao.ErrUserCanvasNotFound so the
// handler layer can map every "not yours" case to the same 404 envelope
// — see plan §4.8 IDOR mitigation.
//
// DAO-error sanitization (v3.5.2 follow-up): the raw userTenantDAO and
// canvasDAO errors are wrapped with ErrAgentStorageError so mapAgentError
// classifies them as CodeServerError (500) with a sanitized message —
// the original DAO error string (DSN, table name, gorm stack frame)
// MUST NOT reach the client. Sentinels (ErrUserCanvasNotFound) pass
// through unchanged so they keep mapping to the 404 envelope.
//
// This is the FIRST storage access path RunAgent hits, so leaving the
// raw errors here would have left a DAO-string leak in the very first
// hop — the earlier af2ac2eda + 804854a5e commits only sanitized the
// version-read path, missing the canvas-access path.
func (s *AgentService) loadCanvasForUser(ctx context.Context, canvasID string, operation permission.Operation) (*entity.UserCanvas, error) {
userID := permission.UserIDFromContext(ctx)
if canvasID == "" || userID == "" {
return nil, dao.ErrUserCanvasNotFound
}
if err := permission.NewDatabaseChecker(dao.DB).CheckResource(ctx, permission.ResourceRef{Kind: permission.ResourceKindCanvas, ID: canvasID}, operation); err != nil {
if errors.Is(err, permission.ErrResourceNotFound) || errors.Is(err, permission.ErrPermissionDenied) {
return nil, dao.ErrUserCanvasNotFound
}
return nil, fmt.Errorf("check canvas %q permission for user %s: %w: %w", canvasID, userID, err, ErrAgentStorageError)
}
row, err := s.canvasDAO.GetByID(ctx, dao.DB, canvasID)
if err != nil {
if errors.Is(err, dao.ErrUserCanvasNotFound) {
return nil, err
}
return nil, fmt.Errorf("load canvas %q for user %s: %w: %w", canvasID, userID, err, ErrAgentStorageError)
}
return row, nil
}
// GetAgent returns a single canvas visible to the requesting user.
// Returns dao.ErrUserCanvasNotFound (not 403) when the canvas is missing
// or belongs to another user.
func (s *AgentService) GetAgent(ctx context.Context, canvasID string) (*entity.UserCanvas, error) {
canvasInstance, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationRead)
if err != nil {
return nil, err
}
access, err := permission.NewDatabaseChecker(dao.DB).ResolveAccess(ctx, permission.ResourceRef{
Kind: permission.ResourceKindCanvas,
ID: canvasID,
})
if err != nil {
return nil, err
}
canvasInstance.OperatorPermission = access.PermissionMask
return canvasInstance, nil
}
// GetLastPublishTime returns the update_time of the most recently updated
// released version, or nil when the canvas has never been published.
// Mirrors the last_publish_time computation in Python's get_agent handler.
func (s *AgentService) GetLastPublishTime(ctx context.Context, canvasID string) (*int64, error) {
version, err := s.versionDAO.GetLatestReleased(ctx, dao.DB, canvasID)
if err != nil {
if errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
return nil, nil
}
return nil, err
}
return version.UpdateTime, nil
}
// UpdateAgent applies a draft patch to user_canvas. Settings updates may omit
// dsl; in that case the existing draft DSL must be preserved.
//
// Shared users may edit canvas content, but only the owner may change its
// visibility.
func (s *AgentService) UpdateAgent(ctx context.Context, canvasID string, patch map[string]interface{}) error {
userID := permission.UserIDFromContext(ctx)
canvasInstance, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationUpdate)
if err != nil {
return err
}
ownerUserID := canvasInstance.UserID
if v, ok := patch["permission"]; ok {
shareErr := permission.NewDatabaseChecker(dao.DB).CheckResource(ctx, permission.ResourceRef{Kind: permission.ResourceKindCanvas, ID: canvasID}, permission.OperationShare)
if shareErr != nil {
if !errors.Is(shareErr, permission.ErrPermissionDenied) {
return fmt.Errorf("check agent sharing permission: %w", shareErr)
}
requested := strings.ToLower(strings.TrimSpace(fmt.Sprint(v)))
current := strings.ToLower(strings.TrimSpace(canvasInstance.Permission))
if requested != current {
return fmt.Errorf("user %s has no permission to edit permission", userID)
}
delete(patch, "permission")
}
}
updates := map[string]interface{}{}
for _, key := range []string{"title", "avatar", "description", "permission", "canvas_type", "canvas_category"} {
if value, ok := patch[key]; ok && value != nil {
if key == "title" {
title, ok := value.(string)
if !ok {
return fmt.Errorf("update agent %s: title must be a string", canvasID)
}
title = strings.TrimSpace(title)
if err := common.ValidateNameRunes(title, common.NameLimit255); err != nil {
return fmt.Errorf("update agent %s: %w", canvasID, err)
}
value = title
}
if key == "permission" {
if permissionValue, ok := value.(string); ok {
value = strings.ToLower(strings.TrimSpace(permissionValue))
}
}
updates[key] = value
}
}
// Publish flow: the front-end sends release ("true"/true) together with
// dsl via PUT, and Python's update_agent coerces it with
// `bool(req.get("release", ""))` — any non-empty string is truthy.
// Mirror that here so the canvas row and the new version row both carry
// the release flag; an absent release keeps parity with Python, which
// always writes the coerced value (False when missing).
release := false
if value, ok := patch["release"]; ok && value != nil {
switch v := value.(type) {
case bool:
release = v
case string:
release = v != ""
}
}
updates["release"] = release
// Autosave signal (design §5.1): the front-end sends autosave:true on its
// debounced auto-save. An auto-save refreshes ONLY the live draft
// (user_canvas.dsl) and must NOT create a new version. A manual Save (no
// autosave flag, or autosave:false) must both update the draft and INSERT a
// new version row. v5.2 removes the same-DSL in-place refresh dedup, so
// every manual Save produces a version even when the DSL is unchanged.
autosave := false
if value, ok := patch["autosave"]; ok && value != nil {
switch v := value.(type) {
case bool:
autosave = v
case string:
autosave = v != "" && v != "false"
case float64:
autosave = v != 0
}
}
// Optional alias carried on a manual Save (design §4.4 carry-on path).
var aliasPtr *string
if value, ok := patch["alias"]; ok && value != nil {
alias, ok := value.(string)
if !ok {
return fmt.Errorf("update agent %s: alias must be a string", canvasID)
}
alias = strings.TrimSpace(alias)
if err := common.ValidateAliasRunes(alias, common.NameLimit255); err != nil {
return fmt.Errorf("update agent %s: %w", canvasID, err)
}
if alias != "" {
aliasPtr = &alias
}
}
// ApplyVersion restore path: restoring a version refreshes only the live
// draft and must not write user_canvas_version at all. The restored DSL
// already exists as a historical row, so a new row would be a pure
// duplicate counting against the per-canvas version cap. The "apply" flag
// signals this so the version save below is skipped entirely.
applyVersion := false
if value, ok := patch["apply"]; ok && value != nil {
applyVersion = true
}
if title, ok := updatedAgentTitle(canvasInstance, updates); ok {
canvasCategory := updatedAgentCanvasCategory(canvasInstance, updates)
// Exclude the canvas being updated so keeping or only re-casing its
// title does not collide with itself, while a move to a category that
// already holds the title is still rejected.
exists, err := s.canvasDAO.TitleExists(ctx, dao.DB, ownerUserID, canvasCategory, title, canvasID)
if err != nil {
return fmt.Errorf("check duplicate title: %w", err)
}
if exists {
return agentTitleAlreadyExistsError(title)
}
}
if dsl, ok := patch["dsl"]; ok && dsl != nil {
dslMap, ok := dsl.(map[string]interface{})
if !ok {
if typed, ok := dsl.(entity.JSONMap); ok {
dslMap = typed
} else {
return fmt.Errorf("update agent %s: dsl must be an object", canvasID)
}
}
if err := component.ValidateIntegerParameters(dslMap); err != nil {
return fmt.Errorf("update agent %s: %w", canvasID, err)
}
validateEntries := component.ValidateDraftDynamicEntries
if release {
validateEntries = component.ValidateDynamicEntries
}
if err := validateEntries(dslMap); err != nil {
return fmt.Errorf("update agent %s: %w", canvasID, err)
}
if err := validateAgentChatModelReferences(ctx, canvasInstance.EffectiveTenantID(), dslMap, !release); err != nil {
return err
}
updates["dsl"] = entity.JSONMap(dslpkg.NormalizeForCanvas(dslMap))
}
// Build the version options up front so the canvas row update and the
// version save can share one transaction below.
var versionOpts *dao.SaveOrReplaceLatestVersionOptions
if dslValue, ok := updates["dsl"]; ok {
dsl, ok := dslValue.(entity.JSONMap)
if !ok {
return fmt.Errorf("update agent %s: normalized dsl must be an object", canvasID)
}
title := ""
if value, ok := updates["title"]; ok {
title, _ = value.(string)
} else if canvasInstance.Title != nil {
title = *canvasInstance.Title
}
opts := s.saveOrReplaceVersionOptions(canvasID, dsl, title, nil, aliasPtr, release)
// Manual Save (autosave != true) always mints a new version row, even
// when the DSL is identical to the previous one (design §5.1). Auto-save
// never mints a version, and neither does an ApplyVersion restore; both
// leave versionOpts nil so only the live draft is refreshed below.
opts.ForceNew = true
if !autosave && !applyVersion {
versionOpts = &opts
}
}
// The canvas release/DSL update and the version save must commit
// atomically: if the version write fails after the canvas row is
// committed, the canvas is left published (or unpublished) without a
// matching version state.
err = dao.DB.Transaction(func(tx *gorm.DB) error {
if _, err := s.canvasDAO.UpdateFieldsTx(tx, canvasID, updates); err != nil {
return err
}
if versionOpts != nil {
if _, err := s.versionDAO.SaveOrReplaceLatestTx(ctx, tx, *versionOpts); err != nil {
return fmt.Errorf("save version: %w", err)
}
}
return nil
})
if err != nil {
if dao.IsDuplicateKeyErr(err) {
if title, ok := updatedAgentTitle(canvasInstance, updates); ok {
return agentTitleAlreadyExistsError(title)
}
return errors.New("agent title already exists")
}
return fmt.Errorf("update agent %s: %w", canvasID, err)
}
return nil
}
// ResetAgent clears the per-run state of a canvas (history, retrieval,
// memory, path) and zeroes every "sys.*" / "env.*" global, mirroring
// the Python handler at api/apps/restful_apis/agent_api.py:992. The
// reset transform is a pure DSL mutation; the persisted row in
// user_canvas.dsl is rewritten in place and the freshly reset DSL is
// returned so the caller can render it back to the client without an
// extra GET.
//
// Reset does NOT create a new user_canvas_version row. It also does NOT touch
// the in-flight run state of any currently executing canvas session; active
// session cancellation and lease ownership remain the responsibility of the
// run service, not this DSL reset operation.
//
// Errors propagate the same way as GetAgent: a missing canvas, or a
// canvas that the user has no access to, surfaces as
// dao.ErrUserCanvasNotFound so mapAgentError emits the same 404 the
// Python handler does for "canvas not found."
func (s *AgentService) ResetAgent(ctx context.Context, canvasID string) (entity.JSONMap, error) {
row, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationUpdate)
if err != nil {
return nil, err
}
reset := dslpkg.ResetForCanvas(row.DSL)
// Re-normalize through the same entry point UpdateAgent uses so
// any front-end that reads `graph.nodes` / `components[*].obj`
// right after the response sees a renderable shape, not a partial
// reset that left the legacy short-form DSL intact.
row.DSL = dslpkg.NormalizeForCanvas(reset)
row.Release = false
if err = s.canvasDAO.Update(ctx, dao.DB, row); err != nil {
return nil, fmt.Errorf("reset agent %s: %w", canvasID, err)
}
return row.DSL, nil
}
// DeleteAgent removes a canvas and cascades to its user_canvas_version
// rows in a single transaction so a mid-flight failure cannot leave
// orphan version rows. Canvas delete access is decided by the permission
// policy, including its sharing rules.
func (s *AgentService) DeleteAgent(ctx context.Context, canvasID string) error {
if err := permission.NewDatabaseChecker(dao.DB).CheckResource(ctx, permission.ResourceRef{Kind: permission.ResourceKindCanvas, ID: canvasID}, permission.OperationDelete); err != nil {
if errors.Is(err, permission.ErrResourceNotFound) || errors.Is(err, permission.ErrPermissionDenied) {
return ErrAgentNotOwner
}
return fmt.Errorf("check agent deletion permission: %w", err)
}
return dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if _, err := s.versionDAO.DeleteByCanvasIDTx(ctx, tx, canvasID); err != nil {
return fmt.Errorf("delete agent: cascade versions: %w", err)
}
if err := s.canvasDAO.DeleteTx(ctx, tx, canvasID); err != nil {
return fmt.Errorf("delete agent %s: %w", canvasID, err)
}
return nil
})
}
// PublishAgentRequest is the input shape for PublishAgent.
type PublishAgentRequest struct {
Title *string `json:"title,omitempty"`
Description *string `json:"description,omitempty"`
Alias *string `json:"alias,omitempty"`
DSL entity.JSONMap `json:"dsl,omitempty"`
}
func (s *AgentService) PublishAgent(ctx context.Context, canvasID string, req *PublishAgentRequest) (*entity.UserCanvasVersion, error) {
canvasInstance, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationUpdate)
if err != nil {
return nil, err
}
dsl := canvasInstance.DSL
title := canvasInstance.Title
description := canvasInstance.Description
var alias *string
if req != nil {
if req.DSL != nil {
if err := component.ValidateIntegerParameters(req.DSL); err != nil {
return nil, fmt.Errorf("publish agent %s: %w", canvasID, err)
}
dsl = dslpkg.NormalizeForCanvas(req.DSL)
}
if req.Title != nil {
trimmed := strings.TrimSpace(*req.Title)
if err := common.ValidateNameRunes(trimmed, common.NameLimit255); err != nil {
return nil, fmt.Errorf("publish agent %s: %w", canvasID, err)
}
title = &trimmed
}
if req.Description != nil {
description = req.Description
}
if req.Alias != nil {
aliasValue := strings.TrimSpace(*req.Alias)
if err := common.ValidateAliasRunes(aliasValue, common.NameLimit255); err != nil {
return nil, fmt.Errorf("publish agent %s: %w", canvasID, err)
}
alias = &aliasValue
}
}
if title != nil {
if err := common.ValidateNameRunes(*title, common.NameLimit255); err != nil {
return nil, fmt.Errorf("publish agent %s: %w", canvasID, err)
}
}
if err := validateAgentChatModels(ctx, canvasInstance.EffectiveTenantID(), dsl); err != nil {
return nil, err
}
if err := component.ValidateDynamicEntries(dsl); err != nil {
return nil, fmt.Errorf("publish agent %s: %w", canvasID, err)
}
canvasInstance.DSL = dsl
canvasInstance.Title = title
canvasInstance.Description = description
canvasInstance.Release = true
titleStr := ""
if title != nil {
titleStr = *title
}
opts := s.saveOrReplaceVersionOptions(canvasID, dsl, titleStr, description, alias, true)
var row *entity.UserCanvasVersion
if err = dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err = s.canvasDAO.UpdateTx(ctx, tx, canvasInstance); err != nil {
return fmt.Errorf("publish agent %s: update parent: %w", canvasID, err)
}
saved, err := s.versionDAO.SaveOrReplaceLatestTx(ctx, tx, opts)
if err != nil {
return fmt.Errorf("publish agent %s: save version: %w", canvasID, err)
}
row = saved
return nil
}); err != nil {
return nil, err
}
return row, nil
}
func (s *AgentService) saveOrReplaceVersionOptions(canvasID string, dsl entity.JSONMap, title string, description *string, alias *string, release bool) dao.SaveOrReplaceLatestVersionOptions {
versionTitle := buildVersionTitle(title, time.Now())
return dao.SaveOrReplaceLatestVersionOptions{
NewID: common.GenerateUUID(),
UserCanvasID: canvasID,
Title: &versionTitle,
Description: description,
Alias: alias,
DSL: dsl,
Release: release,
SameDSL: func(latestDSL entity.JSONMap) bool {
return reflect.DeepEqual(
entity.JSONMap(dslpkg.NormalizeForCanvas(latestDSL)),
dsl,
)
},
}
}
func buildVersionTitle(agentTitle string, ts time.Time) string {
title := strings.TrimSpace(agentTitle)
if title == "" {
title = "agent"
}
// user_canvas_version.title is VARCHAR(255); reserve room for the timestamp
// suffix so a maximum-length canvas title cannot overflow the version row.
title = utility.TruncateRunes(title, common.VersionBaseTitleLimit)
return fmt.Sprintf("%s_%s", title, ts.Format(common.VersionTitleTimeLayout))
}
// ListVersions returns every version for a canvas the user can see,
// newest first. The parent-canvas access check is enforced before the
// version list is loaded so unauthorized users cannot enumerate version
// ids of canvases they cannot read.
func (s *AgentService) ListVersions(ctx context.Context, canvasID string) ([]*entity.UserCanvasVersion, error) {
if _, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationRead); err != nil {
return nil, err
}
return s.versionDAO.ListByCanvasID(ctx, dao.DB, canvasID)
}
// GetVersion returns a single version of a canvas the user can see.
// Returns dao.ErrUserCanvasVersionNotFound when the version does not
// exist or belongs to a different canvas, and
// dao.ErrUserCanvasNotFound when the parent canvas is not visible to
// the requesting user.
func (s *AgentService) GetVersion(ctx context.Context, canvasID, versionID string) (*entity.UserCanvasVersion, error) {
if versionID == "" {
return nil, dao.ErrUserCanvasVersionNotFound
}
if _, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationRead); err != nil {
return nil, err
}
row, err := s.versionDAO.GetByID(ctx, dao.DB, versionID)
if err != nil {
return nil, err
}
if row.UserCanvasID != canvasID {
return nil, dao.ErrUserCanvasVersionNotFound
}
return row, nil
}
// DeleteVersion removes a single version of a canvas the user can see.
// Returns dao.ErrUserCanvasVersionNotFound when the row does not exist
// (or belongs to a different canvas) and dao.ErrUserCanvasNotFound when
// the parent canvas is not visible to the requesting user.
func (s *AgentService) DeleteVersion(ctx context.Context, canvasID, versionID string) error {
if versionID == "" {
return dao.ErrUserCanvasVersionNotFound
}
canvas, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationUpdate)
if err != nil {
return err
}
row, err := s.versionDAO.GetByID(ctx, dao.DB, versionID)
if err != nil {
return err
}
if row.UserCanvasID != canvasID {
return dao.ErrUserCanvasVersionNotFound
}
// Design B4 / A4: deleting a version is allowed even when bindings
// reference it (the B2.1 dialog already confirmed). Referencing bindings
// simply fall into the Missing state (design section 6.2). For dataflow
// canvases we scan references so the operator gets a warning about the
// affected bindings (design section 12 A4, scan scoped to dataflow only).
if canvas.CanvasCategory == "dataflow_canvas" {
if refs, rerr := s.versionDAO.CountPipelineVersionReferences(ctx, dao.DB, versionID); rerr == nil && refs > 0 {
common.Warn("delete canvas version still referenced by active bindings; referers will enter Missing state",
zap.String("canvas_id", canvasID),
zap.String("version_id", versionID),
zap.Int64("reference_count", refs))
}
}
return dao.DB.Transaction(func(tx *gorm.DB) error {
return s.versionDAO.DeleteTx(ctx, tx, versionID)
})
}
// UpdateVersion patches mutable metadata (alias/title/description) of a single
// version of a canvas the user can update. It never changes the DSL and never
// creates a new version (design G2/§4.4). Returns
// dao.ErrUserCanvasVersionNotFound when the row does not exist or belongs to a
// different canvas, and dao.ErrUserCanvasNotFound when the parent canvas is not
// updatable by the requesting user.
func (s *AgentService) UpdateVersion(ctx context.Context, canvasID, versionID string, patch dao.UserCanvasVersionPatch) error {
if versionID == "" {
return dao.ErrUserCanvasVersionNotFound
}
if _, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationUpdate); err != nil {
return err
}
row, err := s.versionDAO.GetByID(ctx, dao.DB, versionID)
if err != nil {
return err
}
if row.UserCanvasID != canvasID {
return dao.ErrUserCanvasVersionNotFound
}
if patch.Alias != nil {
alias := strings.TrimSpace(*patch.Alias)
if err := common.ValidateAliasRunes(alias, common.NameLimit255); err != nil {
return err
}
patch.Alias = &alias
}
if patch.Title != nil {
title := strings.TrimSpace(*patch.Title)
if err := common.ValidateNameRunes(title, common.NameLimit255); err != nil {
return err
}
patch.Title = &title
}
return dao.DB.Transaction(func(tx *gorm.DB) error {
return s.versionDAO.UpdateTx(ctx, tx, versionID, patch)
})
}
// ApplyVersion restores a saved version's DSL as the live draft, preserving
// the agent's metadata and version history. It never writes
// user_canvas_version: the restored DSL already exists as a historical row,
// so a new one would be a pure duplicate counting against the per-canvas
// version cap.
func (s *AgentService) ApplyVersion(ctx context.Context, canvasID, versionID string) error {
version, err := s.GetVersion(ctx, canvasID, versionID)
if err != nil {
if errors.Is(err, dao.ErrUserCanvasNotFound) || errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
return err
}
return fmt.Errorf("load agent version: %w: %w", err, ErrAgentStorageError)
}
if version.DSL == nil {
return errors.New("agent version has no DSL to apply")
}
// The "apply" flag tells UpdateAgent to skip the version write and refresh
// only the live draft.
return s.UpdateAgent(ctx, canvasID, map[string]interface{}{"dsl": version.DSL, "apply": true})
}
// RunAgent starts a run for the given canvas and returns a channel of
// orchestrator events the HTTP layer streams back as SSE. The driver owns
// the wait-for-user cycle (eino interrupt, gap-analysis §11.6.4): the
// RunFunc returns an interrupt error when a UserFillUp node pauses the
// graph, the driver persists the interrupt id keyed by (canvasID,
// sessionID), and resumes when the next call supplies a non-empty
// userInput — at which point it injects (__resume_interrupt_id__,
// __resume_data__) into root so the RunFunc can call
// compose.ResumeWithData(ctx, id, data) before invoking the workflow.
//
// sessionID is required for the multi-turn cycle: the handler generates
// one (UUID) on the first call and reuses it on follow-up posts. version
// selects the published UserCanvasVersion row; "" uses the latest version.
//
// The per-run RunFunc is built by buildRunFunc — see its doc comment
// for the full production chain (real Compile/Invoke, resume path,
// error-layering contract).
func (s *AgentService) RunAgent(ctx context.Context, canvasID, sessionID, version string, userInput any, files []map[string]interface{}) (<-chan canvas.RunEvent, error) {
userID := permission.UserIDFromContext(ctx)
receivedAt := float64(time.Now().UnixNano()) / 1e9
canvasRow, err := s.loadCanvasForUser(ctx, canvasID, permission.OperationRun)
if err != nil {
return nil, err
}
agentTenantID := canvasRow.EffectiveTenantID()
newSession := sessionID == ""
if sessionID == "" {
sessionID = common.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 err := checkAgentSessionRunPermission(ctx, sessionID); err != nil {
return nil, fmt.Errorf("RunAgent: session %q not found: %w", sessionID, err)
}
}
messageID := common.GenerateToken()
questionSaved := false
persistQuestion := func() error {
if questionSaved || s.api4ConversationDAO == nil || dao.DB == nil {
return nil
}
session, err := s.api4ConversationDAO.GetMetadataBySessionID(ctx, dao.DB, sessionID, canvasID)
if err != nil {
return fmt.Errorf("RunAgent: load session: %w: %w", err, ErrAgentStorageError)
}
if session == nil {
return nil
}
if err := checkAgentSessionRunPermission(ctx, sessionID); err != nil {
return fmt.Errorf("RunAgent: session %q not found: %w", sessionID, err)
}
if err := s.persistAgentRunQuestion(ctx, canvasID, sessionID, messageID, userInput, receivedAt); err != nil {
return fmt.Errorf("RunAgent: persist question: %w: %w", err, ErrAgentStorageError)
}
questionSaved = true
return nil
}
if err := persistQuestion(); err != nil {
return nil, err
}
runID := runIDFor(canvasID, map[string]any{"session_id": sessionID})
lockToken := common.GenerateToken()
runCtx, cancelRun := context.WithCancel(ctx)
// Keep workflow cancellation separate from event-consumer cancellation.
// An explicit session cancellation should still reach an attached client,
// while a disconnected HTTP request must stop event delivery promptly.
runCtx = canvas.WithEventContext(runCtx, ctx)
active := &activeAgentRun{
userID: userID,
canvasID: canvasID,
sessionID: sessionID,
leaseToken: lockToken,
cancelRun: cancelRun,
}
releaseLocal := func() {
s.runMu.Lock()
if s.activeSessions[sessionID] == active {
delete(s.activeSessions, sessionID)
}
s.runMu.Unlock()
}
// Accept concurrent questions, but serialize stateful runs so checkpoints
// and persisted DSL cannot be overwritten by another run of this session.
wait := time.NewTicker(100 * time.Millisecond)
defer wait.Stop()
for {
if err := ctx.Err(); err != nil {
cancelRun()
return nil, err
}
registered := true
if s.runTracker != nil {
var registerErr error
registered, registerErr = s.runTracker.RegisterActiveSession(ctx, canvas.ActiveSession{
SessionID: sessionID,
Token: lockToken,
UserID: userID,
CanvasID: canvasID,
RunID: runID,
})
if registerErr != nil {
cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
_, _ = s.runTracker.ReleaseActiveSession(cleanupCtx, sessionID, lockToken)
cleanupCancel()
cancelRun()
return nil, fmt.Errorf("RunAgent: register active session: %w: %w", registerErr, ErrAgentStorageError)
}
}
if registered {
s.runMu.Lock()
_, busy := s.activeSessions[sessionID]
if !busy {
s.activeSessions[sessionID] = active
}
s.runMu.Unlock()
if !busy {
break
}
if s.runTracker != nil {
cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
_, _ = s.runTracker.ReleaseActiveSession(cleanupCtx, sessionID, lockToken)
cleanupCancel()
}
}
if err := persistQuestion(); err != nil {
cancelRun()
return nil, err
}
select {
case <-ctx.Done():
cancelRun()
return nil, ctx.Err()
case <-wait.C:
}
}
if s.runTracker == nil {
// Without the distributed registry, clear a marker left by a prior
// local run before starting the watcher. A concurrent local Cancel also
// calls cancelRun directly, so this cleanup cannot lose that signal.
clearCtx, cancelClear := context.WithTimeout(ctx, time.Second)
_ = canvas.ClearCancel(clearCtx, sessionID)
cancelClear()
}
releaseRegistration := func() {
cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
if s.runTracker != nil {
_, releaseErr := s.runTracker.ReleaseActiveSession(cleanupCtx, sessionID, lockToken)
if releaseErr != nil {
common.Warn("agent run: release active session failed", zap.String("session_id", sessionID), zap.Error(releaseErr))
}
} else {
_ = canvas.ClearCancel(cleanupCtx, sessionID)
}
cleanupCancel()
releaseLocal()
}
// Start cancellation and lease watchers as soon as the active registration
// is visible. This keeps the lease alive during initialization and preserves
// a cancel marker published before Compile/Invoke begins.
watchCtx, cancelWatch := context.WithCancel(context.WithoutCancel(ctx))
go canvas.WatchCancel(watchCtx, sessionID, active.requestCancel)
if s.runTracker != nil {
go s.runTracker.WatchActiveSession(watchCtx, sessionID, lockToken, active.requestCancel)
}
checkCtx, cancelCheck := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
if requested, checkErr := canvas.CancelRequested(checkCtx, sessionID); checkErr != nil {
common.Warn("agent run: initial cancel check failed",
zap.String("session_id", sessionID), zap.Error(checkErr))
} else if requested {
active.requestCancel()
}
cancelCheck()
// Until the Runner goroutine takes ownership, every initialization error
// must release the active lease and any marker written for this token.
registrationHandedOff := false
defer func() {
if registrationHandedOff {
return
}
cancelWatch()
cancelRun()
releaseRegistration()
}()
// DSL resolution: without an explicit version id the run executes the
// canvas's current editable draft (canvasRow.DSL) — the DSL the user just
// clicked "Run" against, which the front-end auto-saves before running.
// Published version rows are only executed through the released path
// (runReleasedAgent, embed with release=true) or an explicit ?version= id.
//
// IDOR guard: when the caller supplies an explicit version id, the row we
// load must belong to canvasID — otherwise any caller who knows a foreign
// version id could run that canvas's DSL against their own canvas (a
// clear integrity/authorization boundary breach). GetVersion (at the read
// path) already enforces this check; the run path mirrors it and surfaces
// ErrUserCanvasVersionNotFound so the handler maps to a clean 404 rather
// than silently using the foreign DSL. DB-side errors are wrapped with
// ErrAgentStorageError so raw DAO strings (DSNs, table names, gorm stack
// frames) never reach the client.
//
// The buildRunFunc placeholder branch is reserved for the rare
// "canvas exists but has no DSL at all" edge case.
var (
versionRow *entity.UserCanvasVersion
dsl map[string]any
)
channelRun, _ := ctx.Value(channelAgentRunContextKey{}).(bool)
refreshSessionDSL := channelRun && version == ""
paused := s.runner != nil && s.runner.Peek(canvasID, sessionID)
var resumeInterruptID string
if userInput != nil && s.runTracker != nil {
interruptID, ok, err := s.runTracker.GetInterruptID(ctx, runID)
if err != nil && refreshSessionDSL {
return nil, fmt.Errorf("RunAgent: load pending interrupt: %w: %w", err, ErrAgentStorageError)
}
if err == nil && ok {
resumeInterruptID = interruptID
paused = true
}
}
if version != "" {
row, err := s.versionDAO.GetByID(ctx, dao.DB, version)
if err != nil {
if errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
return nil, fmt.Errorf("RunAgent: load version %q: %w", version, err)
}
return nil, fmt.Errorf("RunAgent: load version %q: %w: %w", version, err, ErrAgentStorageError)
}
if row.UserCanvasID != canvasID {
// IDOR — caller asked to run version X against canvas
// Y, but version X belongs to canvas Z. Surface the
// same "not found" envelope the read path uses.
return nil, fmt.Errorf(
"RunAgent: version %q belongs to canvas %q, not %q: %w",
version, row.UserCanvasID, canvasID,
dao.ErrUserCanvasVersionNotFound,
)
}
versionRow = row
dsl = normalisedDSLForRun(versionRow)
} else if len(canvasRow.DSL) > 0 {
dsl = dslpkg.NormalizeForRun(canvasRow.DSL)
}
sessionFound := false
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 existingSession != nil {
if err := checkAgentSessionRunPermission(ctx, sessionID); err != nil {
return nil, fmt.Errorf("RunAgent: session %q not found: %w", sessionID, err)
}
}
sessionFound = existingSession != nil
if existingSession != nil && len(existingSession.DSL) > 0 {
if refreshSessionDSL && !paused {
dsl = refreshChannelAgentDSL(dsl, existingSession.DSL)
} else {
// A paused execution must resume the graph that wrote its checkpoint.
dsl = dslpkg.NormalizeForRun(existingSession.DSL)
}
}
}
if err := validateAgentChatModels(ctx, agentTenantID, dsl); err != nil {
return nil, err
}
if err := component.ValidateDynamicEntries(dsl); err != nil {
return nil, fmt.Errorf("RunAgent: %w", err)
}
// 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,
// but must never inherit conversation history or an execution path.
dsl = dslpkg.ResetForNewSession(dsl)
if err = s.createAgentRunSession(ctx, sessionID, canvasID, dsl, versionRow, userInput); err != nil {
return nil, fmt.Errorf("RunAgent: create session %q: %w: %w", sessionID, err, ErrAgentStorageError)
}
}
if err := persistQuestion(); err != nil {
return nil, err
}
run := s.buildRunFunc(canvasID, versionRow, dsl)
root := map[string]any{
"__message_id__": messageID,
"canvas_id": canvasID,
"version_id": version,
"session_id": sessionID,
"user_id": userID,
}
if refreshSessionDSL && !paused {
root["__force_new_run__"] = true
}
// Drop failed first-touch sessions only when there was no user question.
if (!sessionFound || newSession) && stringifyAgentUserInput(agentRunQuery(userInput)) == "" {
root["__drop_session_on_failure__"] = true
}
// The stable run id is derived from the canvas and session. It is only a
// checkpoint/status storage key; session_id remains the public run and
// cancellation identity.
// Recover a pending UserFillUp interrupt from Redis when this request
// lands on a different process.
if resumeInterruptID != "" {
root["__resume_interrupt_id__"] = resumeInterruptID
root["__resume_data__"] = userInput
}
if userInput != nil {
root["user_input"] = userInput
}
if messages := openAICompatMessagesFromContext(ctx); len(messages) > 0 {
root["openai_messages"] = messages
}
if len(files) > 0 {
root["files"] = files
}
if dsl != nil {
root["__dsl_present__"] = true
}
// Webhook payload injection. Only RunAgentWithWebhook sets this
// context value; the chat / agent-run paths leave it nil so the
// existing surface is unchanged. The 'BEGIN' component reads
// inputs["webhook_payload"] and writes it to state.Sys so
// downstream components can read sys.webhook_payload.
if payload, ok := ctx.Value(webhookPayloadKey{}).(map[string]any); ok && payload != nil {
root["webhook_payload"] = payload
}
// Runtime resources use the canvas tenant; root["user_id"] retains the
// authenticated runner for caller-scoped permission checks and conversation data.
root["tenant_id"] = agentTenantID
// Preserve the historical RunTracker tenant dimension separately.
// Existing tests and log filters expect the caller's joined tenant id
// in the run hash.
if tenantIDs, terr := s.userTenantDAO.GetTenantIDsByUserID(ctx, dao.DB, userID); terr == nil && len(tenantIDs) > 0 {
root["run_tenant_id"] = tenantIDs[0]
} else if terr != nil {
common.Warn("service: RunAgent userTenantDAO.GetTenantIDsByUserID (best-effort, run tracker tenant not populated)",
zap.String("user_id", userID),
zap.Error(terr))
}
// v3.6.1 diagnostic: log what RunAgent put into root so we can
// confirm tenant_id / user_id / session_id / user_input all
// reached the buildRunFunc closure (which runs in the runner's
// goroutine, possibly after a context switch).
common.Debug("RunAgent root",
zap.String("canvasID", canvasID),
zap.String("userID", userID),
zap.String("sessionID", sessionID),
zap.Any("tenantID", root["tenant_id"]),
zap.Any("userInput", root["user_input"]))
// Cancellation of the HTTP request must reach the workflow, but it must
// not stop the Redis watchers while the real Runner goroutine is still
// unwinding. Otherwise, a non-cooperative external call can outlive the
// lease, allowing a second process to acquire the same session. The
// detached watcher context is canceled only after inner has closed and
// cleanup has taken ownership of the lease release.
lifecycleDone := make(chan struct{})
go func() {
select {
case <-ctx.Done():
active.requestCancel()
case <-lifecycleDone:
}
}()
inner := s.runner.Run(runCtx, run, canvasID, sessionID, userInput, root)
out := make(chan canvas.RunEvent, 8)
go func() {
defer close(out)
defer func() {
cancelWatch()
close(lifecycleDone)
if ctx.Err() != nil {
active.cancelRequested.Store(true)
}
cancelRun()
if active.cancelRequested.Load() {
if s.runTracker != nil {
statusCtx, cancelStatus := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
err := s.runTracker.MarkCancelled(statusCtx, runID)
cancelStatus()
if err != nil {
common.Warn("agent run: mark session cancelled failed",
zap.String("session_id", sessionID), zap.Error(err))
}
}
}
releaseRegistration()
}()
for ev := range inner {
if ev.SessionID == "" {
ev.SessionID = sessionID
}
select {
case out <- ev:
case <-ctx.Done():
// Keep draining the Runner so its managed workflow can unwind,
// but stop forwarding frames to a disconnected client.
}
}
}()
registrationHandedOff = true
return out, nil
}
// runReleasedAgent runs the most recently published version of a canvas.
// Public agent runs keep using RunAgent's editable/latest-version behavior;
// this path is reserved for the agentbot release=true contract.
func (s *AgentService) runReleasedAgent(ctx context.Context, canvasID, sessionID string, userInput any, files []map[string]interface{}) (<-chan canvas.RunEvent, error) {
version, err := s.versionDAO.GetLatestReleased(ctx, dao.DB, canvasID)
if err != nil {
return nil, fmt.Errorf("load latest released version for canvas %q: %w", canvasID, err)
}
return s.RunAgent(ctx, canvasID, sessionID, version.ID, userInput, files)
}
// validateAgentChatModels rejects stale Agent model references before execution.
// It resolves models in the canvas tenant and checks access for the actual
// caller. Agent components always invoke a chat model; model-free
// canvases contain no Agent component and pass through.
func validateAgentChatModels(ctx context.Context, tenantID string, dsl map[string]any) error {
return validateAgentChatModelReferences(ctx, tenantID, dsl, false)
}
func validateAgentChatModelReferences(ctx context.Context, tenantID string, dsl map[string]any, draft bool) error {
c, err := canvas.DecodeFromDSL(dsl)
if err != nil {
return nil
}
modelFactory := NewModelFactory()
for _, node := range c.Components {
if !strings.EqualFold(node.Obj.ComponentName, "Agent") {
continue
}
for _, field := range []string{"model_id", "llm_id"} {
if value := node.Obj.Params[field]; value != nil {
if _, ok := value.(string); !ok {
return fmt.Errorf("Agent %s must be a string", field)
}
}
}
modelRef, ok := node.Obj.Params["model_id"].(string)
if !ok {
modelRef, _ = node.Obj.Params["llm_id"].(string)
}
if _, err := modelFactory.ResolveInfo(permission.WithTenantID(ctx, tenantID), entity.ModelTypeChat, modelRef); err != nil {
if draft && (errors.Is(err, errModelConfigUnavailable) || errors.Is(err, gorm.ErrRecordNotFound)) && !errors.Is(err, permission.ErrPermissionDenied) && !errors.Is(err, permission.ErrResourceNotFound) {
continue
}
if errors.Is(err, errModelConfigUnavailable) || errors.Is(err, gorm.ErrRecordNotFound) {
return errors.New("The configured chat model is missing or unavailable. Please select a valid model.")
}
return fmt.Errorf("validate Agent chat model: %w: %w", err, ErrAgentStorageError)
}
}
return nil
}
func checkAgentSessionRunPermission(ctx context.Context, sessionID string) error {
err := permission.NewDatabaseChecker(dao.DB).CheckResource(
ctx,
permission.ResourceRef{Kind: permission.ResourceKindAgentSession, ID: sessionID},
permission.OperationRun,
)
if errors.Is(err, permission.ErrPermissionDenied) || errors.Is(err, permission.ErrResourceNotFound) {
return dao.ErrUserCanvasNotFound
}
if err != nil {
return fmt.Errorf("check agent session run permission: %w: %w", err, ErrAgentStorageError)
}
return nil
}
// buildRunFunc assembles the per-run RunFunc the orchestrator (canvas.Runner)
// drives.
//
// Phase 4.4 V2: this is the real Compile/Invoke path. The previous
// V1 echo placeholder returned a synthesized answer without ever
// calling canvas.Compile — every RunAgent invocation pretended to
// run the canvas. The V2 body actually compiles the DSL, attaches
// the CanvasState to ctx via runtime.WithState (so component bodies
// can read it via runtime.GetStateFromContext), invokes the
// workflow, and surfaces real output through the Runner's existing
// answer-extraction contract.
//
// Nil-versionRow guard: the RunAgent call site treats "no version
// published" as a legal state and passes nil. We extract sessionID
// safely and, when both versionRow and dsl are empty, fall back to
// a graceful "no published version" placeholder so the SSE surface
// still flows (TestRunAgent_NoVersionPublishedPlaceholder pins this
// behavior). The placeholder is written into state.Outputs under
// (cpn="answer", bucket="answer") so the answer extraction in
// first-pass lookup picks it up; the same trick the V1 placeholder
// used (the v3.5.2 fix landed this, and we keep it).
//
// Resume path: Runner.Run injects (__resume_interrupt_id__,
// __resume_data__) into root when userInput arrives on a session
// that previously paused at a wait-for-user interrupt. We consume
// them here and decorate ctx with compose.ResumeWithData so the
// targeted UserFillUp node (compile.go:53-55 lists them via
// compose.WithInterruptBeforeNodes) resumes and reads the user's
// follow-up via compose.GetResumeContext.
func (s *AgentService) buildRunFunc(canvasID string, versionRow *entity.UserCanvasVersion, dsl map[string]any) canvas.RunFunc {
return func(ctx context.Context, root map[string]any) (runState *canvas.CanvasState, runErr error) {
if err := ctx.Err(); err != nil {
return nil, err
}
if err := component.ValidateDynamicEntries(dsl); err != nil {
return nil, runtime.NewUserFacingError(err.Error())
}
// Install a per-run token usage sink so every LLM call inside
// this turn records its token usage (the sink is read at the end
// and emitted in workflow_finished). Mirrors Python's
// Canvas.run() installing token_usage_sink + langfuse_run_attrs.
ctx = tokenizer.WithRunUsage(ctx)
// Extract the event channel + metadata injected by Runner.Run.
events, _ := root["__events__"].(chan canvas.RunEvent)
messageID, _ := root["__message_id__"].(string)
sessionID, _ := root["__session_id__"].(string)
userID, _ := root["user_id"].(string)
// A failed first-touch run with no question should not leave an empty session.
// Sessions with accepted user questions remain in history on failure.
// Interrupts (UserFillUp waits) and user-initiated cancels keep
// the row: both are resumable, visible states, not failures.
if dropOnFailure, _ := root["__drop_session_on_failure__"].(bool); dropOnFailure {
delete(root, "__drop_session_on_failure__")
defer func() {
if runErr == nil || canvas.IsInterruptError(runErr) || errors.Is(runErr, context.Canceled) {
return
}
if s.api4ConversationDAO == nil || dao.DB == nil {
return
}
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
defer cancel()
if _, err := s.api4ConversationDAO.DeleteBySessionIDAndAgentID(cleanupCtx, dao.DB, sessionID, canvasID); err != nil {
common.Warn("agent run: drop failed-run session failed",
zap.String("canvas_id", canvasID),
zap.String("session_id", sessionID),
zap.Error(err))
}
}()
}
// Install per-run Langfuse correlation attrs so LLM calls inside
// this turn are grouped by session/user. Mirrors Python's
// Canvas.run() setting langfuse_run_attrs.
ctx = tokenizer.WithRunAttrs(ctx, &tokenizer.RunAttrs{
SessionID: sessionID,
UserID: userID,
})
// Helper to build an SSE event with metadata.
emit := func(typ, data string) {
if events == nil {
return
}
canvas.PushEvent(ctx, events, canvas.RunEvent{
Type: typ, Data: data,
MessageID: messageID,
CreatedAt: time.Now().Unix(),
SessionID: sessionID,
})
}
// usagePayload returns the aggregated per-run token usage as a
// JSON-serializable map, or nil when no sink was installed.
usagePayload := func() map[string]int {
sink := tokenizer.GetRunUsage(ctx)
if sink == nil {
return nil
}
pt, ct, tt, calls := sink.Snapshot()
return map[string]int{
"prompt_tokens": pt,
"completion_tokens": ct,
"total_tokens": tt,
"calls": calls,
}
}
startedAt := float64(time.Now().UnixNano()) / 1e9
userInput := root["user_input"]
resumeID, isResume := root["__resume_interrupt_id__"].(string)
if !isResume || resumeID == "" {
wsData, _ := json.Marshal(map[string]any{"inputs": userInput})
emit("workflow_started", string(wsData))
}
runID := runIDFor(canvasID, root)
state := canvas.NewCanvasState(runID, sessionID)
// Graceful placeholder: no version published AND no DSL.
if versionRow == nil && len(dsl) == 0 {
answer := fmt.Sprintf("No published version found for canvas %q — publish a version before running.", canvasID)
state.RecordOutput("answer", "answer", answer)
if err := s.persistAgentRunSession(ctx, canvasID, sessionID, messageID, userInput, answer, "", nil, dsl, state, true); err != nil {
return nil, canvas.NewInternalRunError(fmt.Errorf("persist agent session: %w: %w", err, ErrAgentStorageError))
}
// Emit a message event so the SSE surface matches the
// normal-completion shape (test asserts message +
// workflow_finished + done for the placeholder path).
msgData, _ := json.Marshal(canvas.MessageEvent{Content: answer})
meData, _ := json.Marshal(canvas.MessageEndEvent{})
emit("message", string(msgData))
emit("message_end", string(meData))
wfPayload := map[string]any{"outputs": answer}
if u := usagePayload(); u != nil {
wfPayload["usage"] = u
}
wfData, _ := json.Marshal(wfPayload)
emit("workflow_finished", string(wfData))
return state, nil
}
// DSL → *Canvas.
c, err := decodeCanvasFromDSL(dsl)
if err != nil {
s.markAgentSessionFailed(ctx, canvasID, sessionID, "decode: "+err.Error())
s.markRunFailed(ctx, runID, "decode: "+err.Error())
return nil, err
}
// Close MCP tool adapters and any other closeable resources
// held by the canvas after execution completes. Mirrors
// Python's finally: canvas.close() in canvas_service.py.
defer c.Close()
// Store events channel + run metadata on the context so the
// per-node statePre/statePost wrappers (in scheduler.go) can
// emit node_started / node_finished events at the correct
// per-node lifecycle points. Context is used (rather than
// state.Sys) because eino's WithGenLocalState creates a fresh
// CanvasState per run — only the context thread survives from
// the service layer into the state handlers.
ctx2 := canvas.WithRunMeta(ctx, &canvas.RunMeta{
Events: events,
MessageID: messageID,
SessionID: sessionID,
})
ctx2 = runtime.WithDeferredNodeRegistry(ctx2)
agentMessageEmit, agentMessageFinalize, agentMessageReset := makeAgentMessageDeltaEmitterWithFinalizer(emit)
ctx2 = runtime.WithAgentMessageEmitterControl(ctx2, agentMessageEmit, agentMessageFinalize, agentMessageReset)
ctx2 = runtime.WithCanvasMessageEmitter(ctx2, func(content string) {
emitAgentMessageEvent(emit, canvas.MessageEvent{Content: content})
})
ctx2 = runtime.WithCanvasMessageEventEmitter(ctx2, func(content string, startToThink, endToThink bool) {
emitAgentMessageEvent(emit, canvas.MessageEvent{
Content: content,
StartToThink: startToThink,
EndToThink: endToThink,
})
})
// Seed initial env/sys values from the Canvas DSL globals.
// Python's self.globals dict stores "sys.*" and "env.*" under
// their full dotted keys; the Go port splits these into Sys /
// Env / Globals maps so GetVar("env.counter") can look up
// Env["counter"] directly. Without seeding, Env starts empty
// and every env.* reference resolves to nil (unresolved ref).
if c.Globals != nil {
for k, v := range c.Globals {
if strings.HasPrefix(k, "sys.") {
state.SetSys(strings.TrimPrefix(k, "sys."), v)
} else if strings.HasPrefix(k, "env.") {
state.SetEnv(strings.TrimPrefix(k, "env."), v)
} else {
state.SetGlobal(k, v)
}
}
}
state.SetHistory(c.History)
if messages, ok := root["openai_messages"].([]map[string]interface{}); ok && len(messages) > 1 {
state.SetHistory(openAICompatPriorHistory(messages))
}
state.SetMemory(c.Memory)
state.EnsureSysDate()
query := agentRunQuery(userInput)
state.SetSys("query", query)
state.AppendCurrentUser(query)
state.AppendSysHistory("user: " + renderUserHistoryValue(query))
// Trusted caller identity is seeded through the same entry the debug
// endpoint uses, so both paths agree on sys.user_id / sys.tenant_id.
seedUserID, _ := root["user_id"].(string)
seedTenantID, _ := root["tenant_id"].(string)
state.SeedIdentity(seedUserID, seedTenantID)
if canvasID != "" {
state.SetSys("canvas_id", canvasID)
}
if sessionID != "" {
state.SetSys("session_id", sessionID)
}
if rawFiles, ok := root["files"].([]map[string]interface{}); ok && len(rawFiles) > 0 {
// Only used for ParseAgentUploads (read-only); nil DocRemover means
// this FileService MUST NOT be used for DeleteFiles.
fileSvc := file.NewFileService(nil)
files, ferr := fileSvc.ParseAgentUploads(ctx, rawFiles, beginLayoutRecognize(c))
if ferr != nil {
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "parse files: "+ferr.Error())
s.markRunFailed(ctx2, runID, "parse files: "+ferr.Error())
return nil, fmt.Errorf("parse agent files: %w", ferr)
}
state.SetSys("files", files)
}
state.IncrementConversationTurns()
ctx2 = runtime.WithState(ctx2, state)
// Resume path. The user input is the resume payload for the
// previously-paused UserFillUp node — it should NOT also be
// presented to UserFillUp:Menu (the first interactive node)
// as a fresh "menu selection". Without this distinction, on
// the follow-up RunAgent call sys.query=resume_payload would
// be consumed by initialUserFillUpData in the menu body, the
// menu would pick up the resume text as a brand-new branch
// choice, Switch:Route would route to that branch, and the
// previously-paused branch would be silently dropped (the
// "second input doesn't resume" symptom). Clear sys.query so
// the menu's initial-input fast path returns false and the
// body falls through to compose.Interrupt — the menu pauses
// for fresh input next time the user actually wants a
// different branch.
if isResume && resumeID != "" {
resumeData := root["__resume_data__"]
delete(root, "__resume_interrupt_id__")
delete(root, "__resume_data__")
state.SetSys("query", "")
ctx2 = compose.ResumeWithData(ctx2, resumeID, resumeData)
}
if s.runTracker != nil {
_ = s.runTracker.Start(ctx2, runID, canvasID,
tenantIDFromRoot(root), "")
}
// Compile.
var cc *canvas.CompiledCanvas
switch {
case s.checkpointStore != nil && s.stateSerializer != nil:
cc, err = canvas.Compile(ctx2, c,
canvas.WithCheckPointStore(s.checkpointStore),
canvas.WithStateSerializer(s.stateSerializer),
)
case s.checkpointStore != nil:
cc, err = canvas.Compile(ctx2, c,
canvas.WithCheckPointStore(s.checkpointStore),
)
default:
cc, err = canvas.Compile(ctx2, c)
}
if err != nil {
common.Debug("RunAgent compile err",
zap.String("canvas", canvasID),
zap.String("session", sessionID),
zap.String("run", runID),
zap.String("type", fmt.Sprintf("%T", err)),
zap.Error(err))
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "compile: "+err.Error())
s.markRunFailed(ctx2, runID, "compile: "+err.Error())
if _, ok := errors.AsType[*runtime.UserFacingError](err); ok {
return nil, err
}
if errors.Is(err, agenttool.ErrExeSQLNoCredentials) {
return nil, runtime.NewUserFacingError("ExeSQL configuration is incomplete. Set the database connection details before running the agent.")
}
return nil, canvas.NewInternalRunError(
fmt.Errorf("canvas compile: %w: %w", ErrAgentStorageError, err),
)
}
cpID := ""
if s.checkpointStore != nil {
cpID = runID
}
// Invoke.
var invokeOpts []compose.Option
if cpID != "" {
invokeOpts = []compose.Option{compose.WithCheckPointID(cpID)}
}
if forceNewRun, _ := root["__force_new_run__"].(bool); forceNewRun {
// Completed checkpoints retain node state from the previous graph.
invokeOpts = append(invokeOpts, compose.WithForceNewRun())
}
// On a resume, the user input is the resume payload for the
// previously-paused UserFillUp node — it does NOT represent
// a fresh sys.query. The 'BEGIN' node writes inputs["query"]
// straight into state.Sys["query"] (begin.go:76), and
// UserFillUp:Menu's initialUserFillUpData reads sys.query
// back to drive the menu's initial-input fast path. If we
// pass userInput through here on a resume, the menu would
// re-consume the resume text as a brand-new branch choice
// and Switch:Route would route to a fresh branch — the
// previously-paused branch would be silently dropped (the
// "second input doesn't resume" symptom reported for
// categorize / iteration / code / wait_input etc.).
wfInput := agentWorkflowInput(userInput)
if isResume && resumeID != "" {
wfInput = map[string]any{"query": ""}
}
runStartedAt := time.Now()
workflowOutput, invokeErr := cc.Workflow.Invoke(ctx2, wfInput, invokeOpts...)
err = invokeErr
if errors.Is(err, context.Canceled) || errors.Is(ctx2.Err(), context.Canceled) {
// A user stop or client disconnect must not be turned into a
// failed/succeeded run and must not append a synthetic assistant
// message after the workflow has observed cancellation.
return nil, context.Canceled
}
if cpID != "" && s.runTracker != nil {
_ = s.runTracker.AttachCheckpoint(ctx2, runID, cpID)
}
// Collect thinking and references from the state snapshot.
// node_finished events are already emitted per-node by the
// statePost wrappers in scheduler.go.
var thinking string
var legacyReference []interface{}
now := float64(time.Now().UnixNano()) / 1e9
for _, bucket := range state.Snapshot() {
if v, ok := bucket["thinking"].(string); ok && v != "" && thinking == "" {
thinking = v
}
if v, ok := bucket["reference"].([]interface{}); ok {
legacyReference = append(legacyReference, v...)
}
}
referencePayload := agentRunReferencePayload(c, state, legacyReference)
assistantOutput := terminalCanvasOutput(c, state, workflowOutput, runStartedAt)
// The selected Message owns the answer, including empty text when it
// intentionally selected attachments only.
answer, _ := assistantOutput["content"].(string)
downloads := assistantOutput["downloads"]
attachment, _ := assistantOutput["attachment"].(map[string]any)
// Release any deferred Agent node that was not consumed because the
// downstream Message was skipped by an exception/branch path.
runtime.CompleteAllDeferredNodes(ctx2)
runtime.FinalizeAgentMessage(ctx2)
messageEventsEmitted := runtime.AgentMessageEventsEmittedRun(ctx2)
messageEventsSuppressed := runtime.AgentMessageEventsSuppressedRun(ctx2)
shouldEmitMessage := messageEventsEmitted || !messageEventsSuppressed
if err != nil {
common.Debug("RunAgent invoke err",
zap.String("canvas", canvasID),
zap.String("session", sessionID),
zap.String("run", runID),
zap.String("type", fmt.Sprintf("%T", err)),
zap.Error(err))
if canvas.IsInterruptError(err) {
resumeID := canvas.RootInterruptID(canvas.ExtractInterruptContexts(err))
if resumeID != "" && s.runTracker != nil {
_ = s.runTracker.AttachInterrupt(ctx2, runID, resumeID)
_ = s.runTracker.MarkWaiting(ctx2, runID)
}
if answer != "" {
appendAssistantHistory(state, partialAssistantOutput(answer, downloads, attachment))
}
if persistErr := s.persistAgentRunSession(ctx, canvasID, sessionID, messageID, userInput, answer, thinking, referencePayload, dsl, state, answer != ""); persistErr != nil {
return nil, canvas.NewInternalRunError(
fmt.Errorf("persist interrupted agent session: %w: %w", persistErr, ErrAgentStorageError),
)
}
if answer != "" && shouldEmitMessage {
if !messageEventsEmitted {
emitAgentMessageEvents(emit, answer, thinking, referencePayload)
}
meData, _ := json.Marshal(canvas.MessageEndEvent{
Attachment: attachment,
Reference: referencePayload,
})
emit("message_end", string(meData))
}
return state, err
}
if failureText := deferredAgentStreamFailureText(err); failureText != "" {
visibleAnswer := answer
if visibleAnswer == "" && !messageEventsEmitted && shouldEmitMessage {
emitAgentMessageEvents(emit, failureText, thinking, referencePayload)
visibleAnswer = failureText
}
if persistErr := s.persistAgentRunSession(ctx, canvasID, sessionID, messageID, userInput, visibleAnswer, thinking, referencePayload, dsl, state, visibleAnswer != ""); persistErr != nil {
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "persist session: "+persistErr.Error())
s.markRunFailed(ctx2, runID, "persist session: "+persistErr.Error())
return nil, canvas.NewInternalRunError(
fmt.Errorf("persist agent session: %w: %w", persistErr, ErrAgentStorageError),
)
}
if shouldEmitMessage {
meData, _ := json.Marshal(canvas.MessageEndEvent{
Attachment: attachment,
Reference: referencePayload,
})
emit("message_end", string(meData))
}
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "invoke: "+err.Error())
s.markRunFailed(ctx2, runID, "invoke: "+err.Error())
return state, nil
}
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "invoke: "+err.Error())
s.markRunFailed(ctx2, runID, "invoke: "+err.Error())
return nil, canvasInvokeError(err)
}
// Persist the Agent answer for subsequent Agent prompts. The terminal
// Message output is presentation data and may wrap the answer with
// template literals; retaining it in the prompt history makes the model
// reproduce and amplify those literals on later turns.
appendAssistantHistory(state, partialAssistantOutput(answer, downloads, attachment))
if persistErr := s.persistAgentRunSession(ctx, canvasID, sessionID, messageID, userInput, answer, thinking, referencePayload, dsl, state, true); persistErr != nil {
s.markAgentSessionFailed(ctx2, canvasID, sessionID, "persist session: "+persistErr.Error())
s.markRunFailed(ctx2, runID, "persist session: "+persistErr.Error())
return nil, canvas.NewInternalRunError(
fmt.Errorf("persist agent session: %w: %w", persistErr, ErrAgentStorageError),
)
}
if !messageEventsEmitted && shouldEmitMessage {
emitAgentMessageEvents(emit, answer, thinking, referencePayload)
}
if shouldEmitMessage {
meData, _ := json.Marshal(canvas.MessageEndEvent{
Attachment: attachment,
Reference: referencePayload,
})
emit("message_end", string(meData))
}
// Emit workflow_finished with the final outputs and aggregated
// per-run token usage across all LLM calls in this turn.
wfPayload := map[string]interface{}{
"inputs": map[string]any{"query": userInput},
"outputs": workflowOutputsFromTerminal(assistantOutput),
"elapsed_time": now - startedAt,
"created_at": now,
}
if u := usagePayload(); u != nil {
wfPayload["usage"] = u
}
wfData, _ := json.Marshal(wfPayload)
emit("workflow_finished", string(wfData))
s.markRunSucceeded(ctx2, runID)
return state, nil
}
}
func beginLayoutRecognize(c *canvas.Canvas) string {
if c == nil {
return ""
}
for _, comp := range c.Components {
if !strings.EqualFold(comp.Obj.ComponentName, "Begin") {
continue
}
layout, _ := comp.Obj.Params["layout_recognize"].(string)
return layout
}
return ""
}
func (s *AgentService) createAgentRunSession(
ctx context.Context,
sessionID, agentID string,
runDSL map[string]any,
versionRow *entity.UserCanvasVersion,
userInput any,
) error {
if s == nil || s.api4ConversationDAO == nil {
return errors.New("agent session storage is not configured")
}
userID := permission.UserIDFromContext(ctx)
if userID == "" {
return permission.ErrUnauthenticated
}
source := "agent"
name := deriveAgentSessionName(userInput)
if channelName := agentChannelNameFromContext(ctx); channelName != "" {
name = channelSessionName(name, channelName)
}
session := &entity.API4Conversation{
ID: sessionID,
Name: &name,
DialogID: agentID,
UserID: userID,
ExpUserID: &userID,
Message: json.RawMessage(`[]`),
Source: &source,
DSL: entity.JSONMap(runDSL),
}
if versionRow != nil {
session.VersionTitle = versionRow.Title
}
return s.api4ConversationDAO.Create(ctx, dao.DB, session)
}
// deriveAgentSessionName mirrors Python's
// `req.get("name") or (query[:250] if query else "") or ""` — the
// session name defaults to the first 250 runes of the user's input
// so the exploration sidebar shows a meaningful title.
func deriveAgentSessionName(userInput any) string {
var text string
if m, ok := userInput.(map[string]any); ok {
// A dict-shaped input carries the user's message under
// query/question; serialising the whole dict would leak
// `{"query":...}` — or `{}` for an empty dict — into the
// session list as the title.
for _, key := range []string{"query", "question"} {
if s, ok := m[key].(string); ok && s != "" {
text = s
break
}
}
if text == "" && len(m) > 0 {
text = stringifyAgentUserInput(m)
}
} else {
text = stringifyAgentUserInput(userInput)
}
runes := []rune(text)
if len(runes) > 250 {
runes = runes[:250]
}
return string(runes)
}
// alone for first-touch runs, canvasID + sessionID for resumed runs
// (so two concurrent sessions on the same canvas don't collide in
// the snapshot map).
func runIDFor(canvasID string, root map[string]any) string {
if s, ok := root["session_id"].(string); ok && s != "" {
return canvasID + "-" + s
}
return canvasID
}
func workflowOutputs(content string, downloads, attachment any) any {
if emptyDownloadValue(downloads) && emptyAttachmentValue(attachment) {
return content
}
out := map[string]any{"content": content}
if !emptyDownloadValue(downloads) {
out["downloads"] = downloads
}
if !emptyAttachmentValue(attachment) {
out["attachment"] = attachment
}
return out
}
// workflowOutputsFromTerminal preserves the terminal component's complete
// visible content in workflow_finished while retaining the established compact
// string shape when it has no downloads or attachment.
func workflowOutputsFromTerminal(output map[string]any) any {
if len(output) == 0 {
return ""
}
content, _ := output["content"].(string)
return workflowOutputs(content, output["downloads"], output["attachment"])
}
// emptyAttachmentValue reports whether an attachment descriptor is
// absent or empty (nil or an empty map), matching the omitempty
// semantics of the message_end frame.
func emptyAttachmentValue(value any) bool {
if value == nil {
return true
}
if m, ok := value.(map[string]any); ok {
return len(m) == 0
}
return false
}
func emptyDownloadValue(value any) bool {
if value == nil {
return true
}
v := reflect.ValueOf(value)
switch v.Kind() {
case reflect.Slice, reflect.Array, reflect.Map:
return v.Len() == 0
default:
return false
}
}
func (s *AgentService) persistAgentRunQuestion(ctx context.Context, agentID, sessionID, messageID string, userInput any, receivedAt float64) error {
if sessionID == "" || s == nil || s.api4ConversationDAO == nil || dao.DB == nil {
return nil
}
userID := permission.UserIDFromContext(ctx)
text := stringifyAgentUserInput(agentRunQuery(userInput))
if text == "" {
return nil
}
message := map[string]interface{}{"role": "user", "content": text, "id": messageID, "created_at": receivedAt}
return s.api4ConversationDAO.UpdateHistory(ctx, dao.DB, sessionID, agentID, userID, nil, dao.ConversationHistoryUpdate{Message: message})
}
func (s *AgentService) persistAgentRunSession(
ctx context.Context,
agentID, sessionID, messageID string,
userInput any,
answer string,
thinking string,
reference map[string]interface{},
runDSL map[string]any,
state *canvas.CanvasState,
appendAssistantMessage bool,
) error {
now := float64(time.Now().UnixNano()) / 1e9
if sessionID == "" || s == nil || s.api4ConversationDAO == nil || dao.DB == nil {
return nil
}
userID := permission.UserIDFromContext(ctx)
history := dao.ConversationHistoryUpdate{}
if stringifyAgentUserInput(agentRunQuery(userInput)) != "" {
history.QuestionID = messageID
}
if appendAssistantMessage {
history.Message = map[string]interface{}{"role": "assistant", "content": agentSessionMessageContent(answer, thinking), "id": messageID, "created_at": now, "reference": normalizeAgentReferenceEntry(reference)}
}
updates := map[string]interface{}{
"round": gorm.Expr("COALESCE(round, 0) + 1"),
"errors": nil,
}
if state != nil {
updates["dsl"] = buildPersistedAgentDSL(runDSL, state)
}
return s.api4ConversationDAO.UpdateHistory(ctx, dao.DB, sessionID, agentID, userID, updates, history)
}
// refreshChannelAgentDSL keeps conversation data while replacing the workflow.
func refreshChannelAgentDSL(dsl, previous map[string]any) map[string]any {
dsl = dslpkg.ResetForNewSession(dsl)
for _, key := range []string{"history", "memory"} {
if value, ok := previous[key]; ok {
dsl[key] = value
}
}
globals, _ := dsl["globals"].(map[string]any)
if globals == nil {
globals = map[string]any{}
dsl["globals"] = globals
}
oldGlobals, _ := previous["globals"].(map[string]any)
variables, _ := dsl["variables"].(map[string]any)
oldVariables, _ := previous["variables"].(map[string]any)
for key, value := range oldGlobals {
switch key {
case "sys.history", "sys.conversation_turns":
globals[key] = value
default:
if !strings.HasPrefix(key, "env.") {
continue
}
name := strings.TrimPrefix(key, "env.")
if current, ok := globals[key]; ok &&
reflect.TypeOf(current) == reflect.TypeOf(value) &&
reflect.DeepEqual(variables[name], oldVariables[name]) {
globals[key] = value
}
}
}
return dsl
}
func buildPersistedAgentDSL(runDSL map[string]any, state *canvas.CanvasState) entity.JSONMap {
dsl := make(entity.JSONMap, len(runDSL)+3)
for key, value := range runDSL {
dsl[key] = value
}
if state == nil {
return dsl
}
globals := make(map[string]any)
if existing, ok := dsl["globals"].(map[string]any); ok {
for key, value := range existing {
globals[key] = value
}
}
sysValues, envValues, globalValues := state.SnapshotNamespaces()
for key := range globals {
switch {
case strings.HasPrefix(key, "sys."):
if value, exists := sysValues[strings.TrimPrefix(key, "sys.")]; exists {
globals[key] = value
}
case strings.HasPrefix(key, "env."):
if value, exists := envValues[strings.TrimPrefix(key, "env.")]; exists {
globals[key] = value
}
default:
if value, exists := globalValues[key]; exists {
globals[key] = value
}
}
}
for key, value := range globalValues {
if strings.HasPrefix(key, "begin@") {
globals[key] = value
}
}
for _, key := range []string{"query", "user_id", "conversation_turns", "files", "history", "date"} {
if value, exists := sysValues[key]; exists {
globals["sys."+key] = value
}
}
dsl["globals"] = globals
dsl["history"] = canvas.EncodeHistory(state.SnapshotHistory())
dsl["memory"] = canvas.EncodeMemory(state.SnapshotMemory())
return dsl
}
func agentRunReferencePayload(c *canvas.Canvas, state *canvas.CanvasState, legacyChunks []interface{}) map[string]interface{} {
var reference map[string]interface{}
if state != nil {
reference = state.GetRetrievalReference()
}
if len(reference) == 0 {
if len(legacyChunks) == 0 {
return nil
}
reference = map[string]interface{}{
"chunks": legacyChunks,
"doc_aggs": []interface{}{},
"total": len(legacyChunks),
}
}
if c != nil && state != nil {
snapshot := state.Snapshot()
hasAgent, cite := false, false
for cpnID, component := range c.Components {
if !strings.EqualFold(component.Obj.ComponentName, "Agent") || len(snapshot[cpnID]) == 0 {
continue
}
hasAgent = true
if enabled, _ := component.Obj.Params["cite"].(bool); enabled {
cite = true
break
}
}
if hasAgent && !cite {
delete(reference, "doc_aggs")
}
}
return reference
}
func stringifyAgentUserInput(userInput any) string {
switch v := userInput.(type) {
case nil:
return ""
case string:
return v
default:
if b, err := json.Marshal(v); err == nil {
return string(b)
}
return fmt.Sprint(v)
}
}
func agentRunQuery(userInput any) any {
if values, ok := userInput.(map[string]any); ok {
return values["query"]
}
return userInput
}
func agentWorkflowInput(userInput any) map[string]any {
if values, ok := userInput.(map[string]any); ok {
return maps.Clone(values)
}
return map[string]any{"query": userInput}
}
func appendAssistantHistory(state *canvas.CanvasState, payload map[string]any) {
if state == nil {
return
}
state.AppendHistory("assistant", payload)
state.AppendSysHistory("assistant: " + pythonHistoryRepr(payload))
}
func partialAssistantOutput(answer string, downloads, attachment any) map[string]any {
output := map[string]any{"content": answer}
if !emptyDownloadValue(downloads) {
output["downloads"] = downloads
}
if !emptyAttachmentValue(attachment) {
output["attachment"] = attachment
}
return output
}
func terminalCanvasOutput(
c *canvas.Canvas,
state *canvas.CanvasState,
workflowOutput map[string]any,
runStartedAt time.Time,
) map[string]any {
terminalIDs := make([]string, 0)
messageIDs := make([]string, 0)
if c != nil {
for cpnID, component := range c.Components {
if strings.EqualFold(component.Obj.ComponentName, "Message") {
messageIDs = append(messageIDs, cpnID)
}
if c.NodeParents[cpnID] != "" || strings.EqualFold(component.Obj.ComponentName, "ExitLoop") {
continue
}
// Successful workflow output names the actual outer terminals,
// including macros whose declared downstream belongs to their body.
if _, ok := workflowOutput[cpnID]; ok || len(component.Downstream) == 0 {
terminalIDs = append(terminalIDs, cpnID)
}
}
}
sort.Strings(terminalIDs)
sort.Strings(messageIDs)
for _, cpnID := range terminalIDs {
if output, ok := workflowOutput[cpnID].(map[string]any); ok && len(output) > 0 {
return cloneCanvasOutput(output)
}
}
if state != nil {
snapshot := state.Snapshot()
for _, cpnID := range terminalIDs {
if output := snapshot[cpnID]; len(output) > 0 {
created, _ := output["_created_time"].(string)
createdAt, err := time.Parse(time.RFC3339Nano, created)
if err == nil && !createdAt.Before(runStartedAt) {
return cloneCanvasOutput(output)
}
}
}
// A Message may have emitted a prompt before the next node paused.
// Persist that partial answer, but never replay an earlier turn.
var partial map[string]any
latest := runStartedAt
for _, cpnID := range messageIDs {
output := snapshot[cpnID]
created, _ := output["_created_time"].(string)
createdAt, err := time.Parse(time.RFC3339Nano, created)
if err == nil && !createdAt.Before(latest) {
partial, latest = output, createdAt
}
}
if partial != nil {
return cloneCanvasOutput(partial)
}
}
return map[string]any{}
}
func cloneCanvasOutput(input map[string]any) map[string]any {
output := make(map[string]any, len(input))
for key, value := range input {
switch key {
case "__cpn_id__", "state", "__legacy_noop__":
continue
}
output[key] = value
}
return output
}
func renderUserHistoryValue(value any) string {
switch value := value.(type) {
case string:
return value
case map[string]any:
var buf strings.Builder
encoder := json.NewEncoder(&buf)
encoder.SetEscapeHTML(false)
if err := encoder.Encode(value); err != nil {
return fmt.Sprint(value)
}
return strings.TrimSuffix(buf.String(), "\n")
default:
return pythonHistoryRepr(value)
}
}
func openAICompatPriorHistory(messages []map[string]interface{}) []map[string]any {
lastUser := -1
for i, message := range messages {
if role, _ := message["role"].(string); role == "user" {
lastUser = i
}
}
if lastUser <= 0 {
return nil
}
history := make([]map[string]any, 0, lastUser)
for _, message := range messages[:lastUser] {
role, _ := message["role"].(string)
content, err := NormalizeOpenAIMessageContent(message["content"])
if err != nil || role == "" || content == "" {
continue
}
history = append(history, map[string]any{
"role": role,
"content": content,
})
}
return history
}
func pythonHistoryRepr(value any) string {
switch item := value.(type) {
case nil:
return "None"
case string:
replacer := strings.NewReplacer(
"\\", "\\\\",
"'", "\\'",
"\n", "\\n",
"\r", "\\r",
"\t", "\\t",
)
return "'" + replacer.Replace(item) + "'"
case bool:
if item {
return "True"
}
return "False"
case map[string]any:
keys := make([]string, 0, len(item))
for key := range item {
keys = append(keys, key)
}
sort.Slice(keys, func(i, j int) bool {
leftPriority := pythonOutputKeyPriority(keys[i])
rightPriority := pythonOutputKeyPriority(keys[j])
if leftPriority != rightPriority {
return leftPriority < rightPriority
}
return keys[i] < keys[j]
})
parts := make([]string, 0, len(keys))
for _, key := range keys {
parts = append(parts, pythonHistoryRepr(key)+": "+pythonHistoryRepr(item[key]))
}
return "{" + strings.Join(parts, ", ") + "}"
case []any:
parts := make([]string, 0, len(item))
for _, child := range item {
parts = append(parts, pythonHistoryRepr(child))
}
return "[" + strings.Join(parts, ", ") + "]"
case []string:
parts := make([]string, 0, len(item))
for _, child := range item {
parts = append(parts, pythonHistoryRepr(child))
}
return "[" + strings.Join(parts, ", ") + "]"
default:
return fmt.Sprint(item)
}
}
// pythonOutputKeyPriority reconstructs the order produced by Python's
// ComponentParamBase output dictionaries: declared business outputs first,
// followed by the timing fields added by ComponentBase.invoke(). Message
// declares content then downloads, which is the terminal payload most often
// persisted in conversation history.
func pythonOutputKeyPriority(key string) int {
switch key {
case "content":
return 0
case "downloads":
return 1
case "_created_time":
return 3
case "_elapsed_time":
return 4
default:
return 2
}
}
// tenantIDFromRoot returns the optional run-tracker tenant id that
// RunAgent populated on the root map. Runtime components use
// root["tenant_id"] / state.Sys["tenant_id"] for the canvas tenant, while
// root["user_id"] / state.Sys["user_id"] retain the actual caller. RunTracker
// keeps its historical joined-tenant dimension separately. Empty when absent
// — the RunTracker stores "" as the tenant id, which the test suite exercises.
func tenantIDFromRoot(root map[string]any) string {
if s, ok := root["run_tenant_id"].(string); ok {
return s
}
if s, ok := root["tenant_id"].(string); ok {
return s
}
return ""
}
// deferredAgentStreamFailureText returns the user-facing failure text the
// Message component recorded when its deferred consumption of an Agent
// stream failed. Python surfaces that same text through the failing node's
// outputs into the chat stream instead of aborting the SSE conversation
// with an error frame, so the run handler keeps it in the message flow.
// Cancellation and timeouts stay run-level errors.
func deferredAgentStreamFailureText(err error) string {
if err == nil || errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
return ""
}
var deferred *runtime.DeferredStreamError
if !errors.As(err, &deferred) {
return ""
}
return strings.TrimSpace(deferred.FailureText())
}
func canvasInvokeError(err error) error {
if err == nil {
return nil
}
msg := err.Error()
if strings.Contains(msg, "[GraphRunError] no tasks to execute") &&
strings.Contains(msg, "last completed nodes: [Switch:") {
return errors.New("agent invoke: Switch routing stopped because no connected branch matched the condition; check the Switch branches")
}
return fmt.Errorf("agent invoke: %w", err)
}
// markRunSucceeded records the run as completed successfully via
// the Kvrocks-backed RunTracker. No-op when tracker is nil (test path)
// or when the underlying Redis call fails (degraded boot).
func (s *AgentService) markRunSucceeded(ctx context.Context, runID string) {
if s.runTracker == nil {
return
}
if err := s.runTracker.MarkSucceeded(ctx, runID); err != nil {
common.Warn("service: RunAgent runTracker.MarkSucceeded (best-effort, run not blocked)",
zap.String("run_id", runID),
zap.Error(err))
}
_ = s.runTracker.ClearInterruptID(ctx, runID)
}
// markRunFailed records the run as failed (with reason) via the
// Kvrocks-backed RunTracker. No-op when tracker is nil or the
// underlying Redis call fails.
func (s *AgentService) markRunFailed(ctx context.Context, runID, reason string) {
if s.runTracker == nil {
return
}
if err := s.runTracker.MarkFailed(ctx, runID, reason); err != nil {
common.Warn("service: RunAgent runTracker.MarkFailed (best-effort, run not blocked)",
zap.String("run_id", runID),
zap.String("reason", reason),
zap.Error(err))
}
}
// markAgentSessionFailed keeps the persisted agent log state aligned with the
// run tracker. A streamed failure may still return a user-facing message, but
// it must remain a failed execution in the session history.
func (s *AgentService) markAgentSessionFailed(ctx context.Context, canvasID, sessionID, reason string) {
if s == nil || s.api4ConversationDAO == nil || dao.DB == nil || sessionID == "" {
return
}
userID := permission.UserIDFromContext(ctx)
if err := s.api4ConversationDAO.UpdateHistory(ctx, dao.DB, sessionID, canvasID, userID,
map[string]interface{}{"errors": reason}, dao.ConversationHistoryUpdate{}); err != nil {
common.Warn("agent run: persist failed session status failed",
zap.String("session_id", sessionID), zap.Error(err))
}
}
// normalisedDSLForRun returns the DSL map for the given version, or
// nil when the version has no DSL or is missing. The map is a deep
// copy because canvas.Compile mutates some fields in place; reusing
// the same DSL across concurrent runs would race.
func normalisedDSLForRun(v *entity.UserCanvasVersion) map[string]any {
if v == nil || len(v.DSL) == 0 {
return nil
}
return dslpkg.NormalizeForRun(v.DSL)
}
// CancelSessionRun is the single ordinary-Agent cancellation path. It cancels
// the local run context when present and publishes a session-scoped Redis
// marker for an owning instance. Unknown and finished sessions are idempotent
// successes.
func (s *AgentService) CancelSessionRun(ctx context.Context, sessionID string) error {
userID := permission.UserIDFromContext(ctx)
s.runMu.Lock()
active := s.activeSessions[sessionID]
s.runMu.Unlock()
if active != nil {
if active.userID != userID {
return ErrAgentNotOwner
}
active.requestCancel()
if s.runTracker != nil {
if _, err := s.runTracker.RequestCancelActiveSession(ctx, sessionID, active.leaseToken); err != nil {
common.Warn("agent cancel: redis publish failed", zap.String("session_id", sessionID), zap.Error(err))
}
return nil
}
if err := canvas.RequestCancel(ctx, sessionID); err != nil {
// Local cancellation is already effective; Redis failure only
// prevents cross-instance propagation.
common.Warn("agent cancel: redis publish failed", zap.String("session_id", sessionID), zap.Error(err))
}
return nil
}
if s.runTracker != nil {
remote, err := s.runTracker.GetActiveSession(ctx, sessionID)
if err != nil {
return fmt.Errorf("agent cancel: read active session: %w: %w", err, ErrAgentStorageError)
}
if remote != nil {
if remote.UserID != "" && remote.UserID != userID {
return ErrAgentNotOwner
}
requested, err := s.runTracker.RequestCancelActiveSession(ctx, sessionID, remote.Token)
if err != nil {
return fmt.Errorf("agent cancel: publish remote marker: %w: %w", err, ErrAgentStorageError)
}
if !requested {
return nil
}
return nil
}
}
// A persisted conversation is not evidence of an active run. Once both the
// local registration and the distributed lease are absent, cancellation is
// an idempotent no-op. Publishing a session-scoped marker here would race
// completed-run cleanup and could cancel a later run that reuses sessionID.
return nil
}