Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
package service
import (
"context"
"database/sql"
"errors"
"fmt"
"io"
"slices"
"strings"
"github.com/Tencent/WeKnora/internal/agent"
"github.com/Tencent/WeKnora/internal/agent/approval"
"github.com/Tencent/WeKnora/internal/agent/operations"
"github.com/Tencent/WeKnora/internal/agent/skills"
"github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/application/access"
"github.com/Tencent/WeKnora/internal/application/attachment"
"github.com/Tencent/WeKnora/internal/application/repository"
"github.com/Tencent/WeKnora/internal/background"
"github.com/Tencent/WeKnora/internal/browserskill"
"github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/mcp"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/models/rerank"
"github.com/Tencent/WeKnora/internal/productdocs"
"github.com/Tencent/WeKnora/internal/sandbox"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
secutils "github.com/Tencent/WeKnora/internal/utils"
"gorm.io/gorm"
)
const MAX_ITERATIONS = 100 // Max iterations for agent execution
// dedupStrings removes duplicate strings while preserving the first occurrence order.
func dedupStrings(in []string) []string {
if len(in) == 0 {
return in
}
seen := make(map[string]struct{}, len(in))
out := make([]string, 0, len(in))
for _, s := range in {
if _, ok := seen[s]; ok {
continue
}
seen[s] = struct{}{}
out = append(out, s)
}
return out
}
// withoutString returns the slice with every occurrence of drop removed,
// preserving order.
func withoutString(in []string, drop string) []string {
out := make([]string, 0, len(in))
for _, s := range in {
if s != drop {
out = append(out, s)
}
}
return out
}
// agentHasKnowledgeScope reports whether the agent has any KB retrieval scope for
// this turn. Tag-only @mentions populate SearchTargets (with TagIDs) but leave
// KnowledgeBases / KnowledgeIDs empty — those must still count as in-scope.
func agentHasKnowledgeScope(config *types.AgentConfig) bool {
if config == nil {
return false
}
return types.HasKnowledgeRetrievalScope(
config.SearchTargets,
config.KnowledgeBases,
config.KnowledgeIDs,
)
}
// knowledgeBaseScopesForPrompt returns the KB IDs to show in runtime_context
// metadata, together with the tenant each KB should be queried under.
//
// The tenant map always comes from SearchTargets, which buildSearchTargets has
// already resolved (and authorized) per KB: a directly shared KB carries its
// source tenant there. KnowledgeBases alone cannot tell own from shared KBs —
// both KBSelectionMode="all" and an @mention put shared KB IDs into it.
// KBs missing from the map fall back to the caller's tenant.
func knowledgeBaseScopesForPrompt(config *types.AgentConfig) ([]string, map[string]uint64) {
if config == nil {
return nil, nil
}
kbTenantMap := config.SearchTargets.GetKBTenantMap()
if len(config.KnowledgeBases) > 0 {
return config.KnowledgeBases, kbTenantMap
}
return config.SearchTargets.GetAllKnowledgeBaseIDs(), kbTenantMap
}
// agentService implements agent-related business logic
type agentService struct {
browserSkill *browserskill.Manager
userRepo interfaces.UserRepository
graphRepo interfaces.RetrieveGraphRepository
cfg *config.Config
modelService interfaces.ModelService
mcpServiceService interfaces.MCPServiceService
mcpManager *mcp.MCPManager
eventBus *event.EventBus
db *gorm.DB
webSearchService interfaces.WebSearchService
knowledgeBaseService interfaces.KnowledgeBaseService
knowledgeService interfaces.KnowledgeService
fileService interfaces.FileService
chunkService interfaces.ChunkService
duckdb *sql.DB
wikiPageService interfaces.WikiPageService
tenantService interfaces.TenantService
messageService interfaces.MessageService
memoryService interfaces.MemoryService
storageResolver interfaces.StorageBackendResolver
toolApprovalGate approval.MCPApproval
customAgentService interfaces.CustomAgentService
operationDispatcher operations.Dispatcher
collaboration *AgentCollaboration
sandboxMgr sandbox.Manager
sandboxResolver sandbox.TenantSandboxResolver
sandboxPinner *SessionSandboxPinner
sandboxPolicy WorkspaceSandboxPolicy
hostSandbox sandbox.Manager
hostDesktop bool
hostSkillInstaller sandbox.Manager
hostSkillsRoot string
hostSkillVersionsRoot string
background *BackgroundWork
// shellJobs is an interface so registration can assert ShellJobSubmitter.
// *ShellJobService is the production value. && binds tighter than ||, so
// the availability check groups RemoteAvailable and LocalAvailable.
shellJobs shellJobSource
}
// shellJobSource is the part of *ShellJobService the agent asks about
// availability. Submit is asserted to tools.ShellJobSubmitter at registration.
type shellJobSource interface {
RemoteAvailable() bool
LocalAvailable() bool
}
// NewAgentService creates a new agent service
func NewAgentService(
cfg *config.Config,
modelService interfaces.ModelService,
knowledgeBaseService interfaces.KnowledgeBaseService,
knowledgeService interfaces.KnowledgeService,
fileService interfaces.FileService,
chunkService interfaces.ChunkService,
mcpServiceService interfaces.MCPServiceService,
mcpManager *mcp.MCPManager,
eventBus *event.EventBus,
db *gorm.DB,
webSearchService interfaces.WebSearchService,
duckdb *sql.DB,
wikiPageService interfaces.WikiPageService,
tenantService interfaces.TenantService,
messageService interfaces.MessageService,
memoryService interfaces.MemoryService,
storageResolver interfaces.StorageBackendResolver,
toolApprovalGate approval.MCPApproval,
sandboxMgr sandbox.Manager,
sandboxResolver sandbox.TenantSandboxResolver,
sandboxPinner *SessionSandboxPinner,
sandboxPolicy WorkspaceSandboxPolicy,
hostSandbox HostSandboxManager,
browserSkill *browserskill.Manager,
userRepo interfaces.UserRepository,
graphRepo interfaces.RetrieveGraphRepository,
backgroundWork *BackgroundWork,
shellJobs *ShellJobService,
operationDispatcher *operations.HandlerDispatcher,
customAgentService interfaces.CustomAgentService,
collaboration *AgentCollaboration,
) interfaces.AgentService {
svc := &agentService{
customAgentService: customAgentService,
operationDispatcher: operationDispatcher,
browserSkill: browserSkill,
userRepo: userRepo,
graphRepo: graphRepo,
cfg: cfg,
modelService: modelService,
knowledgeBaseService: knowledgeBaseService,
knowledgeService: knowledgeService,
fileService: fileService,
chunkService: chunkService,
mcpServiceService: mcpServiceService,
mcpManager: mcpManager,
eventBus: eventBus,
db: db,
webSearchService: webSearchService,
duckdb: duckdb,
wikiPageService: wikiPageService,
tenantService: tenantService,
messageService: messageService,
memoryService: memoryService,
storageResolver: storageResolver,
toolApprovalGate: toolApprovalGate,
sandboxMgr: sandboxMgr,
sandboxResolver: sandboxResolver,
sandboxPinner: sandboxPinner,
sandboxPolicy: sandboxPolicy,
hostSandbox: hostSandbox.Manager,
hostDesktop: hostSandbox.Desktop,
background: backgroundWork,
shellJobs: shellJobs,
}
if hostSandbox.SkillsAvailable() {
svc.hostSkillInstaller = hostSandbox.SkillInstaller
svc.hostSkillsRoot = hostSandbox.SkillTree.Root()
svc.hostSkillVersionsRoot = hostSandbox.SkillTree.VersionsRoot()
}
svc.collaboration = collaboration
if collaboration != nil {
collaboration.artifactFiles = svc.collaborationArtifactFiles
}
return svc
}
// CreateAgentEngine creates an agent engine with the given configuration and EventBus.
// History is loaded once per turn by the caller (see service.LoadAgentHistory)
// and handed to AgentEngine.Execute as llmContext; the engine is stateless across turns.
func (s *agentService) CreateAgentEngine(
ctx context.Context,
config *types.AgentConfig,
chatModel chat.Chat,
rerankModel rerank.Reranker,
eventBus *event.EventBus,
sessionID, assistantMessageID string,
) (interfaces.AgentEngine, error) {
logger.Infof(ctx, "Creating agent engine with custom EventBus")
// 1. Validate config
if err := s.ValidateConfig(config); err != nil {
return nil, fmt.Errorf("invalid agent config: %w", err)
}
if chatModel == nil {
return nil, fmt.Errorf("chat model is nil after initialization")
}
if config.LocalBrowserEnabled && (!s.browserSkill.Enabled() || config.SkillInstallMode()) {
return nil, fmt.Errorf("local browser is unavailable for this turn; " +
"enable the browser integration or update the input-bar selection")
}
// 2. Build tool registry
toolRegistry := tools.NewToolRegistry()
if config.MaxToolOutputChars > 0 {
toolRegistry.SetMaxToolOutputSize(config.MaxToolOutputChars)
}
if err := s.registerTools(ctx, toolRegistry, config, rerankModel, chatModel, sessionID); err != nil {
return nil, fmt.Errorf("failed to register tools: %w", err)
}
s.registerMCPTools(ctx, toolRegistry, config)
s.registerOperationTools(ctx, toolRegistry, config)
registerProductDocTools(ctx, toolRegistry, config)
// Register the shell first: file discovery needs a separate tool only
// when no shell is available. File access still follows the sandbox
// capability independently of the existing SkillsEnabled execution gate.
s.registerSandboxShellIfAllowed(ctx, toolRegistry, sessionID, config)
s.registerSandboxFileTools(ctx, toolRegistry, sessionID, config)
s.registerWebPageFiles(ctx, toolRegistry, config, sessionID, assistantMessageID)
attachmentReader := s.registerAttachmentReader(ctx, toolRegistry, config, sessionID)
// Advertise cached service summaries independently of @mentions. Concrete
// tool definitions are published after describe, before the next model request.
toolRegistry.PrepareMCPTools(ctx)
// 3. Resolve knowledge base and selected document metadata
kbInfos, selectedDocs := s.resolveKBAndDocInfos(ctx, config)
// 4. Resolve system prompt template
systemPromptTemplate := ""
if config.UseCustomSystemPrompt || config.SystemPrompt != "" {
systemPromptTemplate = config.ResolveSystemPrompt(config.WebSearchEnabled)
}
// 5. Create engine
engine := agent.NewAgentEngine(
config, chatModel, toolRegistry, eventBus,
kbInfos, selectedDocs, sessionID,
systemPromptTemplate,
)
engine.SetAppConfig(s.cfg)
pinnedMCP := s.resolvePinnedMCPServiceInfos(ctx, config)
s.attachPinnedMCPToolNames(toolRegistry, pinnedMCP)
engine.SetPinnedMentions(
pinnedMCP,
s.resolvePinnedSkillInfos(config),
)
engine.SetQuestionOrigin(s.resolveQuestionOriginInfo(ctx, config.QuestionOrigin, config.SearchTargets, kbInfos))
engine.SetPageContext(s.resolvePageContextInfo(
ctx, config.PageContext, config.SearchTargets, kbInfos, config.OperationsAgentID != ""))
engine.SetAssistantName(config.AssistantName)
// Non-vision chat models use the configured VLM to describe tool images.
// Vision chat models receive the original images after the tool replies.
if config.VLMModelID != "" {
if vlmModel, err := s.modelService.GetVLMModel(ctx, config.VLMModelID); err == nil {
describe := func(ctx context.Context, imgBytes []byte, prompt string) (string, error) {
return vlmModel.Predict(ctx, [][]byte{imgBytes}, prompt)
}
engine.SetImageDescriber(describe)
if attachmentReader != nil && !config.ChatModelSupportsVision {
tenantID, _ := types.SandboxTenantIDFromContext(ctx)
attachmentReader.Images = &attachment.ImageReader{
Model: config.VLMModelID, Describe: describe,
Cache: repository.NewAttachmentDescriptionRepository(s.db, tenantID),
}
}
logger.Infof(ctx, "VLM image describer set for tool result analysis (model: %s)", config.VLMModelID)
} else {
logger.Warnf(ctx, "Failed to load VLM model %s for tool image fallback: %v", config.VLMModelID, err)
}
}
// TenantSkills is the sandbox image. SkillDirs is a host skill tree used
// by tests (and any caller that still points at a host directory); the
// QA path no longer fills it.
//
// The shell is registered above by registerSandboxShellIfAllowed and
// follows SkillsEnabled rather than requiring a ready skill to already
// exist. offerSkills only gates the skills manager that feeds the model
// the installed-skill list and the read_file / shell_exec environment. A sandbox whose skills are still installing —
// or that simply has none yet — therefore gets a shell without an
// empty skills manager or skill tools that cannot succeed.
offerSkills := config.SkillsEnabled &&
(len(config.SkillDirs) > 0 || len(config.TenantSkills) > 0)
if offerSkills {
skillsManager, err := s.initializeSkillsManager(ctx, sessionID, config, toolRegistry)
if err != nil {
logger.Warnf(ctx, "Failed to initialize skills manager: %v", err)
} else if skillsManager != nil {
engine.SetSkillsManager(skillsManager)
logger.Infof(ctx, "Skills manager initialized with %d skills",
len(skillsManager.GetAllMetadata()))
}
}
// Browser operations are native BrowserSkill RPCs, independent of shell and sandbox setup.
if config.LocalBrowserEnabled && s.browserSkill.Enabled() && !config.SkillInstallMode() {
scope := tools.BrowserSkillScope(ctx)
instructions, err := s.browserSearchInstructions(ctx)
if err != nil {
return nil, err
}
toolRegistry.RegisterTool(tools.NewBrowserSkillTool(s.browserSkill, scope, sessionID, instructions))
}
if s.collaboration != nil {
if err := s.collaboration.attach(ctx, engine, toolRegistry, config, sessionID, assistantMessageID); err != nil {
return nil, err
}
}
s.attachBackgroundWork(ctx, engine, toolRegistry, sessionID, assistantMessageID)
toolRegistry.BindSession(sessionID)
engine.SetWorkspaceLayout(s.lookupSessionWorkspaceLayout(ctx, sessionID, config))
return engine, nil
}
// attachBackgroundWork gives the run its background-notice tracker and, when
// the run can submit background work, the work_wait and work_cancel tools.
// Tools are decided here, once per run, and never change mid-run (D10).
func (s *agentService) attachBackgroundWork(
ctx context.Context, engine *agent.AgentEngine, registry *tools.ToolRegistry,
sessionID, assistantMessageID string,
) {
if !s.background.Enabled() {
return
}
tenantID, ok := types.SandboxTenantIDFromContext(ctx)
if !ok || tenantID == 0 {
return
}
ref := interfaces.SessionRef{TenantID: tenantID, SessionID: sessionID}
run := background.NewRunNotices(ref, s.background.Registry, s.background.Inbox)
engine.SetBackgroundRun(run)
submitters := tools.RegisteredBackgroundSubmitters(registry)
if len(submitters) == 0 {
return
}
for _, name := range submitters {
tool, err := registry.GetTool(name)
if err != nil {
continue
}
if async, ok := tool.(*tools.ShellExecAsyncTool); ok {
async.BindBackgroundRun(ref, assistantMessageID, run)
continue
}
// Tests wrap the real tool. The method is the same one: the run's
// SessionRef and RunNotices, whose MarkStarted records a running handle.
if binder, ok := tool.(interface {
BindBackgroundRun(interfaces.SessionRef, string, interface{ MarkStarted(string) })
}); ok {
binder.BindBackgroundRun(ref, assistantMessageID, run)
}
}
pending := func(ctx context.Context) bool {
return engine.HasPendingInput(ctx, sessionID, assistantMessageID)
}
registry.RegisterTool(tools.NewWorkWaitTool(
s.background.Handler, ref, assistantMessageID, run, pending, submitters,
))
registry.RegisterTool(tools.NewWorkCancelTool(s.background.Handler, ref, run))
}
// registerMCPTools registers MCP tools from enabled services for this tenant.
func (s *agentService) registerMCPTools(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
config *types.AgentConfig,
) {
tenantID := uint64(0)
if tid, ok := types.TenantIDFromContext(ctx); ok {
tenantID = tid
}
if tenantID == 0 || s.mcpServiceService == nil || s.mcpManager == nil {
config.MCPSelectionMode = "none"
config.MCPServices = nil
return
}
// Freeze "all" to the services resolved for this turn. A child must not
// silently gain services added after its parent started.
mcpMode := config.MCPSelectionMode
config.MCPSelectionMode = "selected"
selectedIDs := append([]string(nil), config.MCPServices...)
config.MCPServices = nil
if mcpMode == "" {
mcpMode = "all"
}
if mcpMode == "none" {
logger.Infof(ctx, "MCP services disabled by agent config (mode: none)")
return
}
var mcpServices []*types.MCPService
var err error
if mcpMode == "selected" {
if len(selectedIDs) == 0 {
logger.Infof(ctx, "MCP services disabled by agent config (mode: selected, no services)")
return
}
mcpServices, err = s.mcpServiceService.ListMCPServicesByIDs(ctx, tenantID, selectedIDs)
if err != nil {
logger.Warnf(ctx, "Failed to list selected MCP services: %v", err)
return
}
logger.Infof(ctx, "Using %d selected MCP services from agent config", len(mcpServices))
} else {
mcpServices, err = s.mcpServiceService.ListMCPServices(ctx, tenantID)
if err != nil {
logger.Warnf(ctx, "Failed to list MCP services: %v", err)
return
}
}
enabledServices := make([]*types.MCPService, 0)
for _, svc := range mcpServices {
if svc != nil && svc.Enabled {
enabledServices = append(enabledServices, svc)
config.MCPServices = append(config.MCPServices, svc.ID)
}
}
if len(enabledServices) > 0 {
metadataService, ok := s.mcpServiceService.(interfaces.MCPMetadataService)
if !ok {
logger.Warnf(ctx, "MCP metadata storage is unavailable")
return
}
registered, err := tools.RegisterMCPTools(
ctx, toolRegistry, enabledServices, s.mcpManager, s.toolApprovalGate,
config.MCPAuthWaitTimeout, s.mcpServiceService.GetMCPServiceByID,
&tools.MCPMetadataIO{Get: metadataService.GetMCPMetadata, Put: metadataService.PersistMCPMetadata},
)
if err != nil {
logger.Warnf(ctx, "Failed to register MCP directory: %v", err)
} else {
logger.Infof(ctx, "Registered %d MCP service(s) for on-demand discovery", registered)
}
}
}
// resolveKBAndDocInfos loads knowledge base metadata and selected document info for prompt.
func (s *agentService) resolveKBAndDocInfos(
ctx context.Context,
config *types.AgentConfig,
) ([]*agent.KnowledgeBaseInfo, []*agent.SelectedDocumentInfo) {
kbIDs, kbTenantMap := knowledgeBaseScopesForPrompt(config)
kbInfos, err := s.getKnowledgeBaseInfos(ctx, kbIDs, kbTenantMap)
if err != nil {
logger.Warnf(ctx, "Failed to get knowledge base details, using IDs only: %v", err)
kbInfos = make([]*agent.KnowledgeBaseInfo, 0, len(kbIDs))
for _, kbID := range kbIDs {
kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{
ID: kbID,
Name: kbID,
Description: "",
DocCount: 0,
})
}
}
selectedDocs, err := s.getSelectedDocumentInfos(ctx, config.KnowledgeIDs)
if err != nil {
logger.Warnf(ctx, "Failed to get selected document details: %v", err)
selectedDocs = []*agent.SelectedDocumentInfo{}
}
return kbInfos, selectedDocs
}
// registerSandboxFileTools registers list_sandbox_files / read_file /
// write_sandbox_file / edit_sandbox_file.
//
// These expose per-session filesystem access and are a pure sandbox
// capability, not a skill capability. They therefore do NOT follow
// SkillsEnabled: an agent with skills disabled must still be able to read
// staged attachments out of /workspace/input, and to write generated files
// under /workspace. The tools themselves allow those directories (input is
// read-only). Registration only requires a non-disabled sandbox whose
// manager advertises a SessionFileStore.
//
// The skill installer is the exception: write_sandbox_file only accepts
// /workspace, the installer must write .weknora/requirements.json under
// /opt/weknora/tenant/skills, and its prompt forbids touching /workspace
// (that tree is wiped before the snapshot). Offering the file tools made
// the first write of every install fail, then fall back to a shell heredoc.
// Install mode gets write_skill_file / edit_skill_file instead, which write
// the image tree and are scoped to the one skill being installed —
// see registerSkillFileTools.
// registerOperationTools grants the operation catalog to built-in management
// agents. Operations run as the signed-in user through the router, so they
// are withheld from any run that has no such user (API key, embed, IM) and
// from shared agents, whose runs must not mutate the source workspace.
func (s *agentService) registerOperationTools(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
config *types.AgentConfig,
) {
if config == nil || config.OperationsAgentID == "" || config.SharedAgentReadOnly || s.operationDispatcher == nil {
return
}
identity, ok := tools.OperationIdentityFromContext(ctx)
if !ok {
logger.Infof(ctx, "Operation tools withheld: the run has no signed-in web user")
return
}
identity.Agent.AgentID = config.OperationsAgentID
gate, _ := s.toolApprovalGate.(approval.BuiltinApproval)
// The router authorizes every call anyway; checking the role up front
// lets the model tell the user why instead of failing at the router.
operationAccess := operations.Access{
Role: types.CallerFromContext(ctx).Role,
SystemAdmin: types.IsSystemAdminFromContext(ctx),
EnforceRole: s.cfg != nil && s.cfg.Tenant.IsRBACEnforced() && !access.IsCrossTenantSuperuser(ctx, s.cfg),
Level: config.AssistantAccess,
}
catalog := operations.Builtin()
toolRegistry.RegisterTool(tools.NewFindOperationsTool(catalog, operationAccess))
runtime := tools.OperationsRuntime{
Catalog: catalog,
Dispatcher: s.operationDispatcher,
Gate: gate,
Identity: identity,
Access: operationAccess,
}
toolRegistry.RegisterTool(tools.NewRunOperationTool(runtime))
// Opening a page changes nothing; the user saves any form themselves.
toolRegistry.RegisterTool(tools.NewOpenPageTool(runtime))
// Filling the page saves nothing either, but read-only runs only look.
if actor, ok := s.toolApprovalGate.(approval.PageActor); ok && actor != nil {
toolRegistry.RegisterTool(tools.NewViewPageTool(runtime, actor))
toolRegistry.RegisterTool(tools.NewReadPageTool(actor))
toolRegistry.RegisterTool(tools.NewSelectTabTool(actor))
if operationAccess.Level != types.AssistantAccessReadOnly {
toolRegistry.RegisterTool(tools.NewFillPageTool(actor))
}
}
}
// registerProductDocTools gives a granted run the documentation bundled with
// the server. Pages that fail to load are left out; only a library with no
// pages at all withholds the tools, and never the run.
func registerProductDocTools(ctx context.Context, toolRegistry *tools.ToolRegistry, config *types.AgentConfig) {
if config == nil || !config.ProductDocs {
return
}
lib, err := productdocs.Default()
if lib == nil {
logger.Warnf(ctx, "WeKnora documentation tools withheld: %v", err)
return
}
if err != nil {
logger.Warnf(ctx, "WeKnora documentation pages left out: %v", err)
}
toolRegistry.RegisterTool(tools.NewSearchWeKnoraDocsTool(lib))
toolRegistry.RegisterTool(tools.NewReadWeKnoraDocTool(lib))
}
func (s *agentService) registerSandboxFileTools(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
sessionID string,
config *types.AgentConfig,
) {
if config != nil && config.SkillInstallMode() {
logger.Infof(ctx, "Skipping session file tools in skill install mode")
s.registerSkillFileTools(ctx, toolRegistry, sessionID, config)
return
}
sandboxMgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)
if err != nil {
logger.Warnf(ctx, "Failed to resolve sandbox for file tools: %v", err)
return
}
if sandboxMgr == nil {
return
}
if store := sessionSandboxFileStore(sandboxMgr); store != nil {
if _, err := toolRegistry.GetTool(tools.ToolShellExec); err != nil {
toolRegistry.RegisterTool(tools.NewListSandboxFilesTool(store))
}
toolRegistry.RegisterTool(tools.NewReadFileTool(store))
// The per-round completion budget, not a fixed byte count, is what
// bounds one write; the tool advertises a limit derived from it.
toolRegistry.RegisterTool(tools.NewWriteSandboxFileTool(
store,
types.AgentRoundMaxCompletionTokensFor(config.MaxCompletionTokens, config.SandboxConfigID),
))
toolRegistry.RegisterTool(tools.NewEditSandboxFileTool(store))
logger.Infof(ctx, "Registered sandbox file primitives (listing is a no-shell fallback)")
} else {
logger.Infof(ctx, "Sandbox backend does not advertise session filesystem capability; "+
"list_sandbox_files/read_file/write_sandbox_file/edit_sandbox_file not registered")
}
}
// registerSkillFileTools registers write_skill_file / edit_skill_file for the
// built-in skill installer, and for nothing else.
//
// The installer's shell already runs as root inside the skills image root, so
// these tools grant no reach it does not have. They exist because its only
// writer was `cat` with a heredoc: every file went through the shell's
// command-length cap and two levels of quoting, which truncated or mangled
// anything larger than a few lines.
//
// Two conditions gate registration, and both are checked here rather than
// trusted from the caller. SkillInstallMode is settable only through
// EnableSkillInstallMode, which refuses every agent but the built-in
// installer. The skill directory is re-validated against the install path
// rules (host versions root or image root), so a run that somehow carried a
// bad scope gets no writer at all instead of one pointed somewhere unintended.
func (s *agentService) registerSkillFileTools(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
sessionID string,
config *types.AgentConfig,
) {
if config == nil || !config.SkillInstallMode() {
return
}
skillDir, ok := s.validInstallDir(config)
if !ok {
logger.Warnf(ctx, "Install mode carries no valid skill directory (%q); "+
"write_skill_file/edit_skill_file not registered", config.SkillInstallDir())
return
}
sandboxMgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)
if err != nil {
logger.Warnf(ctx, "Failed to resolve sandbox for skill file tools: %v", err)
return
}
if sandboxMgr == nil {
return
}
store, ok := sandboxMgr.(tools.SkillFileStore)
if !ok {
logger.Infof(ctx, "Sandbox backend cannot write the skills image root; "+
"write_skill_file/edit_skill_file not registered")
return
}
toolRegistry.RegisterTool(tools.NewWriteSkillFileTool(store, skillDir))
toolRegistry.RegisterTool(tools.NewEditSkillFileTool(store, skillDir))
logger.Infof(ctx, "Registered write_skill_file and edit_skill_file scoped to %s", skillDir)
}
// validInstallDir is the skill directory the installer may write. Host
// installs live under the local versions root, remote ones under the image.
func (s *agentService) validInstallDir(config *types.AgentConfig) (string, bool) {
if config == nil || !config.SkillInstallMode() {
return "", false
}
if sandbox.IsHostSkillTarget(config.SandboxConfigID) {
if s.hostSkillVersionsRoot == "" {
return "", false
}
return sandbox.ValidatedSkillDirUnder(s.hostSkillVersionsRoot, config.SkillInstallDir())
}
return sandbox.ValidatedImageSkillDir(config.SkillInstallDir())
}
// registerSandboxShellIfAllowed registers shell_exec when this run is
// entitled to a sandbox shell: SkillsEnabled, or the built-in skill
// installer. It does not require a ready skill to already exist, so a
// fresh sandbox still has a way to inspect its environment.
func (s *agentService) registerSandboxShellIfAllowed(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
sessionID string,
config *types.AgentConfig,
) {
if config == nil {
return
}
sandboxMgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)
if err != nil {
logger.Warnf(ctx, "Failed to resolve sandbox for shell_exec: %v", err)
return
}
if sandboxMgr == nil {
return
}
// Remote backends keep the skills entitlement: a shell there only exists
// to serve skill scripts. The host backend IS the feature, so gating it on
// skills would leave Lite with a sandbox nobody can reach.
if sandboxMgr.GetType() != sandbox.SandboxTypeHost &&
!config.SkillsEnabled && !config.SkillInstallMode() {
return
}
s.registerSandboxShellTool(ctx, toolRegistry, sandboxMgr, config)
}
// resolveOpts is every resolve option this run is entitled to. Only the
// built-in installer may reach the install sandbox.
func (s *agentService) resolveOpts(config *types.AgentConfig) []resolveOption {
opts := []resolveOption{withLiteHostSandbox(s.hostSandbox), withLiteDesktop(s.hostDesktop)}
if config != nil && config.SkillInstallMode() && s.hostSkillInstaller != nil {
opts = append(opts, withHostSkillInstaller(s.hostSkillInstaller))
}
return opts
}
// resolveWorkspaceSandbox returns the session's remote sandbox manager, or
// nil when the workspace is disabled / unresolved. Callers that only need
// a capability (file store, shell) use this so they do not have to stand
// up a skills manager.
func (s *agentService) resolveWorkspaceSandbox(
ctx context.Context,
sessionID string,
config *types.AgentConfig,
) (sandbox.Manager, error) {
if s == nil {
return nil, nil
}
configID := ""
if config != nil {
configID = config.SandboxConfigID
}
tenantID, _ := types.TenantIDFromContext(ctx)
sandboxMgr, _, err := resolveSandboxForExecution(
ctx, s.sandboxResolver, s.sandboxMgr, s.sandboxPinner,
tenantID, sessionID, configID, s.sandboxPolicy,
s.resolveOpts(config)...,
)
if err != nil {
return nil, err
}
if sandboxMgr == nil || sandboxMgr.GetType() == sandbox.SandboxTypeDisabled {
return nil, nil
}
return sandboxMgr, nil
}
func (s *agentService) lookupSessionWorkspaceLayout(
ctx context.Context,
sessionID string,
config *types.AgentConfig,
) sandbox.WorkspaceLayout {
configID := ""
if config != nil {
configID = config.SandboxConfigID
}
mgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)
return sessionWorkspaceLayout(ctx, sessionID, mgr, err, s.hostSandbox, configID)
}
// sessionWorkspaceLayout is the layout prompts and attachment staging share.
// A Lite host session must never fall back to /workspace: that path is the
// remote contract, and describing it after a pin/layout miss sends the model
// to a directory that does not exist on the machine.
func sessionWorkspaceLayout(
ctx context.Context,
sessionID string,
mgr sandbox.Manager,
resolveErr error,
host sandbox.Manager,
configID string,
) sandbox.WorkspaceLayout {
if resolveErr != nil || mgr == nil {
return fallbackSessionWorkspaceLayout(host, configID)
}
if provider, ok := mgr.(sandbox.SessionWorkspaceLayoutProvider); ok && provider != nil {
layout, err := provider.SessionWorkspaceLayout(ctx, sessionID)
if err != nil || !layout.HasRoot() {
return sandbox.FailedHostWorkspaceLayout()
}
return layout.Normalized()
}
if mgr.GetType() == sandbox.SandboxTypeHost {
return sandbox.FailedHostWorkspaceLayout()
}
return sandbox.RemoteWorkspaceLayout()
}
func fallbackSessionWorkspaceLayout(host sandbox.Manager, configID string) sandbox.WorkspaceLayout {
if liteHostSandbox(host) != nil && !hasNamedSandboxConfig(configID) {
return sandbox.FailedHostWorkspaceLayout()
}
return sandbox.RemoteWorkspaceLayout()
}
// initializeSkillsManager creates and initializes the skills manager.
//
// The sandbox manager is resolved per workspace: backends differ in
// capability (remote MicroVMs expose a session file store, local does not), so tool
// registration below must inspect this workspace's real manager rather than a
// process-wide singleton. Workspaces without a selected configuration resolve
// to the disabled manager.
func (s *agentService) initializeSkillsManager(
ctx context.Context,
sessionID string,
config *types.AgentConfig,
toolRegistry *tools.ToolRegistry,
) (*skills.Manager, error) {
tenantID, _ := types.TenantIDFromContext(ctx)
sandboxMgr, pin, err := resolveSandboxForExecution(
ctx, s.sandboxResolver, s.sandboxMgr, s.sandboxPinner,
tenantID, sessionID, config.SandboxConfigID, s.sandboxPolicy,
s.resolveOpts(config)...,
)
if err != nil {
return nil, fmt.Errorf("resolve sandbox config for session %s: %w", sessionID, err)
}
if sandboxMgr == nil {
sandboxMgr = sandbox.NewDisabledManager()
}
logger.Infof(ctx, "Workspace sandbox in use: config=%s workspace=%d type=%s",
pin.ConfigID, pin.TenantOr(tenantID), sandboxMgr.GetType())
// Create skills manager
skillsConfig := &skills.ManagerConfig{
SkillDirs: config.SkillDirs,
AllowedSkills: config.AllowedSkills,
Enabled: config.SkillsEnabled,
}
skillsManager := skills.NewManager(skillsConfig, sandboxMgr)
if s.hostDesktop && s.hostSkillsRoot != "" {
skillsManager.WithSkillsRoot(s.hostSkillsRoot)
}
if source := s.tenantSkillSource(ctx, config); source != nil {
skillsManager.WithTenantSource(source)
}
// Initialize (discover skills)
if err := skillsManager.Initialize(ctx); err != nil {
return nil, fmt.Errorf("failed to initialize skills: %w", err)
}
// Skill tools follow SkillsEnabled, not merely sandbox availability: the
// skill installer agent must have shell_exec WITHOUT execute_skill_script,
// since it is the thing installing skills. shell_exec itself is registered
// by registerSandboxShellIfAllowed, not here.
shellEnabled := false
if tool, err := toolRegistry.GetTool(tools.ToolShellExec); err == nil {
if shell, ok := tool.(*tools.ShellExecTool); ok {
shell.WithSkillEnvironment(skillsManager)
shellEnabled = true
}
}
if tool, err := toolRegistry.GetTool(tools.ToolShellExecAsync); err == nil {
if async, ok := tool.(*tools.ShellExecAsyncTool); ok {
async.WithSkillEnvironment(skillsManager)
}
}
if config.SkillsEnabled {
var reader *tools.ReadFileTool
if tool, err := toolRegistry.GetTool(tools.ToolReadFile); err == nil {
reader, _ = tool.(*tools.ReadFileTool)
}
if reader == nil {
// Instructions remain readable without a session filesystem.
reader = tools.NewReadFileTool(nil)
toolRegistry.RegisterTool(reader)
}
reader.WithSkills(skillsManager, shellEnabled)
logger.Infof(ctx, "Attached skill resources to read_file")
}
return skillsManager, nil
}
// tenantSkillSource builds the source for the skills installed into this run's
// sandbox image, or nil when the run has none. The set was already narrowed to
// what this run can invoke when the config was built; nothing here re-decides
// it.
func (s *agentService) tenantSkillSource(
ctx context.Context, config *types.AgentConfig,
) skills.SkillSource {
rows := config.TenantSkills
if len(rows) == 0 {
return nil
}
// The rows were fetched under the caller's workspace, so this is the
// caller's ID; it is read off the row rather than the context so the
// bundle download cannot resolve a different workspace's storage than the
// one the rows came from.
ownerTenantID := rows[0].TenantID
// The closure captures the engine-creation context because loadBundle
// takes no context of its own. That is the turn's context today -
// CreateAgentEngine and engine.Execute are called back to back with the
// same ctx - so it stays live for as long as skill resources can be read. If
// a caller ever creates the engine under a shorter-lived context, bundle
// downloads start failing for installed skills only, and loadBundle needs
// a ctx parameter.
root := sandbox.SkillsImageRoot
if s.hostDesktop && s.hostSkillsRoot != "" {
root = s.hostSkillsRoot
}
return skills.NewTenantSkillSourceAt(root, rows, func(row *types.TenantSkillEntity) ([]byte, error) {
return s.loadInstalledSkillBundle(ctx, ownerTenantID, row)
})
}
// loadInstalledSkillBundle reads the archive one installed skill was built
// from. An object named by the row itself is that archive. A row that only
// names a catalog is answered from the definition's zip, but the definition is
// mutable — registering the same skill again stores a new object and updates
// the catalog ref, while this sandbox goes on running the image built from the
// previous bytes. Skill resources serve what was installed, so a
// definition that has moved on is reported rather than substituted.
func (s *agentService) loadInstalledSkillBundle(
ctx context.Context, tenantID uint64, row *types.TenantSkillEntity,
) ([]byte, error) {
if row == nil {
return nil, errors.New("skill is required")
}
if ref := strings.TrimSpace(row.BundleRef); ref != "" {
return s.readSkillBundle(ctx, tenantID, ref)
}
cid := strings.TrimSpace(row.CatalogID)
if cid == "" || s.db == nil {
return nil, fmt.Errorf("skill %s has no stored bundle; its files cannot be read", row.Name)
}
cat, err := repository.NewTenantSkillRepository(s.db).GetCatalog(ctx, tenantID, cid)
if err != nil {
return nil, err
}
if cat == nil || strings.TrimSpace(cat.BundleRef) == "" {
return nil, fmt.Errorf("skill %s has no stored bundle; its files cannot be read", row.Name)
}
archive, err := s.readSkillBundle(ctx, tenantID, strings.TrimSpace(cat.BundleRef))
if err != nil {
return nil, err
}
// The bytes are checked, not the catalog's recorded digest: a reference and
// a digest that disagree is exactly the case a stamped-but-unstored archive
// leaves behind.
if want := strings.TrimSpace(row.BundleSHA256); want != "" && !archiveMatchesSHA(archive, want) {
return nil, fmt.Errorf(
"skill %s was registered again from a different archive; "+
"reinstall it on this sandbox before reading its files", row.Name)
}
return archive, nil
}
// userEnvResolver builds the per-caller environment resolver for this run, or
// nil when there is no sandbox config to resolve against.
//
// It is built even when the run has no installed skills: the caller's
// config-wide variables are injected into every execution, skills or not.
//
// The repository is constructed from s.db here rather than injected:
// NewAgentService already takes 24 parameters, and this is the only place in
// the agent path that touches the user env table.
func (s *agentService) userEnvResolver(
ctx context.Context, config *types.AgentConfig,
) skills.SkillEnvResolver {
configID := config.SandboxConfigID
if s.hostDesktop {
configID = sandbox.HostSkillTargetID
}
if configID == "" {
return nil
}
rows := config.TenantSkills
if s.db == nil {
// Unreachable in production, but a wiring regression here would drop
// every admin and user value silently and present to a member as "my
// key stopped working" with nothing in the logs.
logger.Warnf(ctx,
"[skill] no database handle: sandbox config %s will run without "+
"any configured environment variable", configID)
return nil
}
// The workspace is read off a row for the same reason tenantSkillSource
// does it: the rows were fetched under the caller's workspace, and a value
// must never be looked up in a different one. With no rows there is nothing
// to disagree with the context.
tenantID, _ := types.TenantIDFromContext(ctx)
if len(rows) > 0 {
tenantID = rows[0].TenantID
}
if tenantID == 0 {
return nil
}
var createTime map[string]string
if !sandbox.IsHostSkillTarget(configID) {
createTime = sandboxCreateTimeEnvVars(ctx, s.db, tenantID, configID)
}
return NewUserEnvResolver(
rows,
repository.NewTenantSkillRepository(s.db),
createTime,
tenantID, configID,
)
}
// sandboxCreateTimeEnvVars loads the config's env_vars once per agent run for
// the required check. They are not re-injected: the container already has them.
// A read failure degrades to empty so a DB blip does not surface as "nobody
// has set this credential".
func sandboxCreateTimeEnvVars(
ctx context.Context, db *gorm.DB, tenantID uint64, configID string,
) map[string]string {
if db == nil || db.Config == nil {
return nil
}
cfg, err := repository.NewTenantSandboxConfigRepository(db).GetByID(ctx, tenantID, configID)
if err != nil {
logger.Warnf(ctx, "[skill] sandbox config %s: create-time env unavailable: %v", configID, err)
return nil
}
if cfg == nil || cfg.Config == nil {
return nil
}
env := map[string]string{}
for name, value := range cfg.Config.EnvVars {
if value != "" {
env[name] = value
}
}
return env
}
// skillEnvCapture writes declared skill credentials a successful shell_exec
// already used, for the current principal. Nil when there is nothing to write
// against. Errors stay inside the callback so a failed persist cannot change
// the tool result the model already received.
func (s *agentService) skillEnvCapture(config *types.AgentConfig) tools.SkillEnvCapture {
if s.db == nil || config == nil {
return nil
}
configID := config.SandboxConfigID
if s.hostDesktop {
// Lite agents store no config; values live under the host target,
// which is where userEnvResolver reads them.
configID = sandbox.HostSkillTargetID
}
if configID == "" {
return nil
}
return func(ctx context.Context, skillName string, pairs map[string]string) {
svc := NewUserEnvService(
repository.NewTenantSkillRepository(s.db),
repository.NewTenantSandboxConfigRepository(s.db),
HostSandboxManager{Desktop: s.hostDesktop},
)
if err := svc.CaptureSkillEnv(ctx, configID, skillName, pairs); err != nil {
logger.Warnf(ctx, "[skill] capture env for %s failed: %v", skillName, err)
}
}
}
// readSkillBundle downloads one uploaded skill archive. It backs skill resource reads for
// installed skills: the image holds the executable copy, but reading a file out
// of it would need a live sandbox, and the archive is byte-identical to what
// was installed.
func (s *agentService) readSkillBundle(
ctx context.Context, tenantID uint64, ref string,
) ([]byte, error) {
if s.storageResolver == nil {
return nil, errors.New("storage resolver is not configured")
}
fs, _, err := s.storageResolver.ResolveFileService(
ctx, &types.Tenant{ID: tenantID}, "", "", "",
)
if err != nil {
return nil, err
}
if fs == nil {
return nil, errors.New("file service is not configured")
}
reader, err := fs.GetFile(ctx, ref)
if err != nil {
return nil, err
}
defer func() { _ = reader.Close() }()
// Bounded because the object is read into memory: the upload limit is the
// only thing that says how large a legitimate archive can be.
archive, err := io.ReadAll(io.LimitReader(reader, maxSkillBundleTotalBytes+1))
if err != nil {
return nil, err
}
if len(archive) > maxSkillBundleTotalBytes {
return nil, fmt.Errorf("skill bundle %s is larger than the upload limit", ref)
}
return archive, nil
}
// registerSandboxShellTool registers the one shell_exec variant this run is
// entitled to.
//
// shell_exec is a remote-only capability: the capability accessors yield nil
// for backends that cannot run session-scoped shell, so the same check works
// for every provider.
//
// The skill installer agent gets the install-mode variant, which runs as root
// and may work inside the skills image root — it exists to install
// dependencies into the image, which the ordinary contract forbids on both
// counts. Every other agent keeps the session-layout executor: remote
// work_dir is the whole sandbox, host work_dir is clamped to writable roots.
// AgentConfig.SkillInstallMode is settable only through
// EnableSkillInstallMode, which refuses every agent but the built-in
// installer, so no tenant agent can reach this branch.
func (s *agentService) registerSandboxShellTool(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
sandboxMgr sandbox.Manager,
config *types.AgentConfig,
) {
if config.SkillInstallMode() {
executor := sessionSandboxInstallShellExecutor(sandboxMgr)
if executor == nil {
logger.Warnf(ctx, "Sandbox backend does not advertise install-mode shell; skill install cannot run")
return
}
skillDir, ok := s.validInstallDir(config)
if !ok {
logger.Warnf(ctx, "Install mode carries no valid skill directory (%q); shell_exec not registered",
config.SkillInstallDir())
return
}
if sandbox.IsHostSkillTarget(config.SandboxConfigID) {
toolRegistry.RegisterTool(tools.NewHostInstallShellExecTool(executor, skillDir))
} else {
toolRegistry.RegisterTool(tools.NewInstallShellExecTool(executor, skillDir))
}
logger.Infof(ctx, "Registered install-mode shell_exec tool (work_dir defaults to %s)", skillDir)
return
}
if executor := sessionSandboxShellExecutor(sandboxMgr); executor != nil {
resolver := s.userEnvResolver(ctx, config)
shell := tools.NewShellExecTool(executor, resolver).WithEnvCapture(s.skillEnvCapture(config))
if gate, ok := s.toolApprovalGate.(tools.HostApproval); ok {
shell = shell.WithHostApproval(gate)
}
toolRegistry.RegisterTool(shell)
logger.Infof(ctx, "Registered shell_exec tool")
s.registerShellExecAsync(ctx, toolRegistry, executor, resolver, config)
} else {
logger.Infof(ctx, "Sandbox backend does not advertise remote shell capability; shell_exec not registered")
}
}
// registerShellExecAsync registers the background shell when this process can
// submit a job. The submitter assertion and the availability check are both
// required. && binds tighter than ||, so the availability disjunction is grouped.
func (s *agentService) registerShellExecAsync(
ctx context.Context,
toolRegistry *tools.ToolRegistry,
executor tools.SandboxCommandExecutor,
resolver skills.SkillEnvResolver,
config *types.AgentConfig,
) {
if s == nil || !s.background.Enabled() || s.shellJobs == nil {
return
}
if submitter, ok := s.shellJobs.(tools.ShellJobSubmitter); ok &&
(s.shellJobs.RemoteAvailable() || s.shellJobs.LocalAvailable()) {
toolRegistry.RegisterTool(tools.NewShellExecAsyncTool(submitter, executor, resolver).
WithEnvCapture(s.skillEnvCapture(config)))
logger.Infof(ctx, "Registered shell_exec_async tool")
}
}
// registerTools registers tools based on the agent configuration
func (s *agentService) registerTools(
ctx context.Context,
registry *tools.ToolRegistry,
config *types.AgentConfig,
rerankModel rerank.Reranker,
chatModel chat.Chat,
sessionID string,
) error {
// Source of truth policy:
// - `config.AllowedTools` is the explicit, user-editable whitelist —
// populated by the agent-type preset on create and freely editable
// afterwards.
// - We never silently *inject* tools the user didn't pick.
// - We still *filter out* tools whose capability prerequisites are missing
// (no KB in scope, no Wiki-capable KB, etc.) so the LLM can't call tools
// that would error at runtime.
// - Agents whose AllowedTools was never set fall back to
// DefaultAllowedTools(); an empty list means no built-in tools.
// tools.EffectiveAllowedTools also rewrites retired names.
allowedTools := tools.EffectiveAllowedTools(config.AllowedTools)
logger.Infof(ctx, "Using allowed tools: %v (set in config: %v)", allowedTools, config.AllowedTools != nil)
if config.SharedAgentReadOnly {
allowedTools = withoutWikiWriteTools(allowedTools)
}
// ---- Capability detection from SearchTargets ----
var hasVectorKB bool
var hasGraphKB bool
var wikiKBIDs []string
wikiRoutes := tools.NewWikiRouteResolver()
for _, target := range config.SearchTargets {
if target == nil || target.KnowledgeBaseID == "" {
continue
}
kb, err := s.knowledgeBaseService.GetKnowledgeBaseByIDOnly(ctx, target.KnowledgeBaseID)
if err != nil {
continue
}
if kb.IsVectorEnabled() || kb.IsKeywordEnabled() {
hasVectorKB = true
}
if kb.IsGraphEnabled() {
hasGraphKB = true
}
if kb.IsWikiEnabled() {
wikiKBIDs = append(wikiKBIDs, kb.ID)
}
}
wikiKBIDs = dedupStrings(wikiKBIDs)
wikiScopes := tools.NewWikiScopesFromSearchTargets(config.SearchTargets, wikiKBIDs)
// Narrow to the KBs that survived scope resolution. Build a fresh slice
// rather than truncating in place, so the argument passed above can never
// be overwritten through a shared backing array.
scopedWikiKBIDs := make([]string, 0, len(wikiScopes))
for _, scope := range wikiScopes {
scopedWikiKBIDs = append(scopedWikiKBIDs, scope.KnowledgeBaseID)
}
wikiKBIDs = scopedWikiKBIDs
hasWikiKB := len(wikiKBIDs) > 0
// Search targets only need read access. Wiki mutations stay on the KBs the
// caller may edit, so a viewer share (or the caller's own agent pointed at
// one) cannot become a write path into another workspace's wiki.
writableWikiKBIDs := intersectStrings(wikiKBIDs, config.WritableKBIDs)
if len(writableWikiKBIDs) == 0 {
allowedTools = withoutWikiWriteTools(allowedTools)
}
// Filter out knowledge base tools if no knowledge scope is configured for this turn.
hasKnowledge := agentHasKnowledgeScope(config)
if !hasKnowledge {
filteredTools := make([]string, 0)
kbTools := map[string]bool{
tools.ToolSearchKnowledge: true,
tools.ToolReadDocument: true,
tools.ToolListDocuments: true,
tools.ToolQueryKnowledgeGraph: true,
tools.ToolDatabaseQuery: true,
tools.ToolDataAnalysis: true,
tools.ToolDataSchema: true,
// Wiki tools also require at least one KB in scope.
tools.ToolWikiReadPage: true,
tools.ToolWikiSearch: true,
tools.ToolWikiFlagIssue: true,
tools.ToolWikiWritePage: true,
tools.ToolWikiReplaceText: true,
tools.ToolWikiRenamePage: true,
tools.ToolWikiDeletePage: true,
tools.ToolWikiReadIssue: true,
tools.ToolWikiUpdateIssue: true,
}
// If no knowledge and no web search, also disable todo_write (not useful for simple chat)
if !config.WebSearchEnabled {
kbTools[tools.ToolTodoWrite] = true
}
for _, toolName := range allowedTools {
if !kbTools[toolName] {
filteredTools = append(filteredTools, toolName)
}
}
allowedTools = filteredTools
logger.Infof(ctx, "Pure Agent Mode: Knowledge base tools filtered out, remaining: %v", allowedTools)
}
// Web capabilities follow the runtime switch even if a saved allowlist names them.
allowedTools = withoutString(allowedTools, tools.ToolWebSearch)
allowedTools = withoutString(allowedTools, tools.ToolWebFetch)
// If web search is enabled, add web_search to allowedTools
if config.WebSearchEnabled {
allowedTools = append(allowedTools, tools.ToolWebSearch)
allowedTools = append(allowedTools, tools.ToolWebFetch)
}
// Long-term memory search follows the memory switches, not the tool list.
// Being able to read memory is already a decision the workspace, the user
// and the agent each get a say in; asking for it a fourth time as a tool
// checkbox would only produce configurations where memory is on but the
// agent cannot reach past what each turn injects for it.
//
// The tool is dropped before it is re-added so that an allowlist which
// still names it — a preset, an API caller, or a config saved while memory
// was on — cannot outlive the switch being turned off.
allowedTools = withoutString(allowedTools, tools.ToolSearchMemory)
if s.memoryService != nil &&
s.memoryService.MemoryAvailable(types.ApplyAgentMemoryPreference(ctx, config.MemoryEnabled)) {
allowedTools = append(allowedTools, tools.ToolSearchMemory)
} else {
logger.Infof(ctx, "search_memory not registered: long-term memory is off for this request")
}
// Tool capability sets — used by the hard safety nets below to drop tools
// whose runtime prerequisite (a matching KB surface) is missing.
//
// NOTE: ragToolSet must stay in sync with frontend `knowledgeBaseTools`
// in AgentEditorModal.vue. These are *all* tools that retrieve/inspect
// content from RAG-style knowledge bases.
ragToolSet := map[string]bool{
tools.ToolSearchKnowledge: true,
tools.ToolQueryKnowledgeGraph: true,
tools.ToolDatabaseQuery: true,
}
// Document readers work on stored chunks, which every KB writes whatever
// its indexing strategy, so a wiki-only scope keeps them: they are how a
// wiki reader checks the source documents a page cites.
documentToolSet := map[string]bool{
tools.ToolReadDocument: true,
tools.ToolListDocuments: true,
}
allWikiToolSet := map[string]bool{
tools.ToolWikiReadPage: true,
tools.ToolWikiSearch: true,
tools.ToolWikiFlagIssue: true,
tools.ToolWikiWritePage: true,
tools.ToolWikiReplaceText: true,
tools.ToolWikiRenamePage: true,
tools.ToolWikiDeletePage: true,
tools.ToolWikiReadIssue: true,
tools.ToolWikiUpdateIssue: true,
}
// Hard safety nets: drop tools whose runtime prerequisite is missing.
// This guards against stale configs where e.g. the user ticked wiki tools
// earlier but later swapped in a non-wiki KB (or vice versa for RAG).
if !hasWikiKB {
filtered := make([]string, 0, len(allowedTools))
dropped := make([]string, 0)
for _, t := range allowedTools {
if allWikiToolSet[t] {
dropped = append(dropped, t)
continue
}
filtered = append(filtered, t)
}
allowedTools = filtered
if len(dropped) > 0 {
logger.Warnf(ctx, "Dropped wiki tools %v because no wiki-capable KB is in scope", dropped)
}
}
if !hasVectorKB {
filtered := make([]string, 0, len(allowedTools))
dropped := make([]string, 0)
for _, t := range allowedTools {
if ragToolSet[t] || (documentToolSet[t] && !hasWikiKB) {
dropped = append(dropped, t)
continue
}
filtered = append(filtered, t)
}
allowedTools = filtered
if len(dropped) > 0 {
logger.Warnf(ctx, "Dropped RAG tools %v because no RAG-capable KB is in scope", dropped)
}
}
// The graph tool only answers on graph-enabled bases; offering it on a
// scope without one produced degraded plain-search results and a tool
// the model kept trying. It follows the graph capability instead.
if !hasGraphKB {
if trimmed := withoutString(allowedTools, tools.ToolQueryKnowledgeGraph); len(trimmed) != len(allowedTools) {
allowedTools = trimmed
logger.Infof(ctx, "Dropped query_knowledge_graph because no graph-enabled KB is in scope")
}
}
// Deduplicate while preserving original order.
allowedTools = dedupStrings(allowedTools)
// logger.Infof(ctx, "Registering tools: %v, webSearchEnabled: %v", allowedTools, config.WebSearchEnabled)
// Register each allowed tool
for _, toolName := range allowedTools {
var toolToRegister types.Tool
switch toolName {
case tools.ToolThinking:
toolToRegister = tools.NewSequentialThinkingTool()
case tools.ToolTodoWrite:
toolToRegister = tools.NewTodoWriteTool()
case tools.ToolAskUser:
asker, ok := s.toolApprovalGate.(approval.UserAsker)
if !ok || asker == nil {
continue
}
toolToRegister = tools.NewAskUserTool(asker)
case tools.ToolSearchKnowledge:
toolToRegister = tools.NewSearchKnowledgeTool(
s.knowledgeBaseService,
s.knowledgeService,
s.chunkService,
config.SearchTargets,
rerankModel,
s.cfg,
).WithContextImages(config.ChatModelSupportsVision)
case tools.ToolReadDocument:
toolToRegister = tools.NewReadDocumentTool(s.knowledgeService, s.chunkService, config.SearchTargets)
case tools.ToolListDocuments:
toolToRegister = tools.NewListDocumentsTool(s.knowledgeService, config.SearchTargets)
case tools.ToolQueryKnowledgeGraph:
var chunkRepo interfaces.ChunkRepository
if s.chunkService != nil {
chunkRepo = s.chunkService.GetRepository()
}
toolToRegister = tools.NewQueryKnowledgeGraphTool(s.knowledgeBaseService, config.SearchTargets).
WithKnowledgeScope(s.knowledgeService).
WithGraph(s.graphRepo, chunkRepo)
case tools.ToolSearchConversations:
// The owner is captured from the caller's identity here, not read
// from the model's arguments, so no prompt can redirect the search
// at somebody else's conversations.
toolToRegister = tools.NewSearchConversationsTool(
s.messageService, types.SessionOwnerIDFromContext(ctx), sessionID)
case tools.ToolSearchMemory:
// Reaching this case means the memory switches were already
// checked above, where the tool is injected. Which memory space is
// read is resolved from the request context inside the service, so
// this tool needs no owner argument and none can be supplied.
toolToRegister = tools.NewSearchMemoryTool(s.memoryService)
case tools.ToolDatabaseQuery:
toolToRegister = tools.NewDatabaseQueryTool(s.db, config.SearchTargets)
case tools.ToolWebSearch:
toolToRegister = tools.NewWebSearchTool(
s.webSearchService,
config.WebSearchMaxResults,
config.WebSearchProviderID,
)
logger.Infof(ctx, "Registered web_search tool for session: %s, maxResults: %d, providerID: %s", sessionID, config.WebSearchMaxResults, config.WebSearchProviderID)
case tools.ToolWebFetch:
toolToRegister = tools.NewWebFetchTool()
logger.Infof(ctx, "Registered web_fetch tool for session: %s", sessionID)
case tools.ToolDataAnalysis:
toolToRegister = tools.NewDataAnalysisTool(s.knowledgeBaseService, s.knowledgeService, s.tenantService, s.fileService, s.duckdb, sessionID, s.storageResolver).
WithSearchTargets(config.SearchTargets)
logger.Infof(ctx, "Registered data_analysis tool for session: %s", sessionID)
case tools.ToolDataSchema:
toolToRegister = tools.NewDataSchemaTool(s.knowledgeService, s.chunkService.GetRepository()).
WithSearchTargets(config.SearchTargets)
logger.Infof(ctx, "Registered data_schema tool")
// Wiki tools — only registered when wiki KBs are detected
case tools.ToolWikiReadPage:
toolToRegister = tools.NewWikiReadPageTool(s.wikiPageService, s.knowledgeService, wikiScopes, wikiRoutes)
case tools.ToolWikiSearch:
toolToRegister = tools.NewWikiSearchTool(s.wikiPageService, s.knowledgeService, wikiScopes, wikiRoutes)
case tools.ToolWikiFlagIssue:
toolToRegister = tools.NewWikiFlagIssueTool(s.wikiPageService, writableWikiKBIDs, wikiRoutes).
WithKnowledgeScope(s.knowledgeService, config.SearchTargets)
case tools.ToolWikiReadIssue:
toolToRegister = tools.NewWikiReadIssueTool(s.wikiPageService, wikiKBIDs)
case tools.ToolWikiUpdateIssue:
toolToRegister = tools.NewWikiUpdateIssueTool(s.wikiPageService, writableWikiKBIDs)
case tools.ToolWikiWritePage:
toolToRegister = tools.NewWikiWritePageTool(
s.wikiPageService, writableWikiKBIDs, s.knowledgeService, wikiRoutes,
).WithSearchTargets(config.SearchTargets)
case tools.ToolWikiReplaceText:
toolToRegister = tools.NewWikiReplaceTextTool(
s.wikiPageService, writableWikiKBIDs, s.knowledgeService, wikiRoutes,
).WithSearchTargets(config.SearchTargets)
case tools.ToolWikiRenamePage:
toolToRegister = tools.NewWikiRenamePageTool(s.wikiPageService, writableWikiKBIDs, wikiRoutes)
case tools.ToolWikiDeletePage:
toolToRegister = tools.NewWikiDeletePageTool(s.wikiPageService, writableWikiKBIDs, wikiRoutes)
case tools.ToolShellExec, tools.ToolReadFile, tools.LegacyToolReadSkill, tools.LegacyToolExecuteSkillScript,
tools.ToolListSandboxFiles, tools.LegacyToolReadSandboxFile, tools.ToolWriteSandboxFile,
tools.ToolEditSandboxFile:
// Bound to the resolved sandbox manager in registerSandboxFileTools
// / registerSandboxShellIfAllowed / initializeSkillsManager.
// Listing them here would warn "Unknown tool: shell_exec" on every
// skill install, then register the real tool a few lines later.
continue
default:
logger.Warnf(ctx, "Unknown tool: %s", toolName)
}
if toolToRegister != nil {
if toolToRegister.Name() != toolName {
logger.Warnf(ctx, "Tool name mismatch: expected %s, got %s", toolName, toolToRegister.Name())
}
confirms := config.OperationsAgentID != "" || config.AssistantAccess != types.AssistantAccessAutoWrite
if risk, writes := assistantWriteToolRisk[toolName]; writes && confirms {
gate, _ := s.toolApprovalGate.(approval.BuiltinApproval)
toolToRegister = tools.NewConfirmedTool(toolToRegister, risk,
operations.Access{Level: config.AssistantAccess}, gate)
}
registry.RegisterTool(toolToRegister)
}
}
logger.Infof(ctx, "Registered %d tools", len(registry.ListTools()))
return nil
}
// assistantWriteToolRisk are the direct tools of the WeKnora assistant that
// change data outside the operation catalog. Its access level decides which
// of them ask the user first, as it does for catalog operations.
var assistantWriteToolRisk = map[string]operations.Risk{
tools.ToolWikiWritePage: operations.RiskWrite,
tools.ToolWikiReplaceText: operations.RiskWrite,
tools.ToolWikiRenamePage: operations.RiskWrite,
tools.ToolWikiFlagIssue: operations.RiskWrite,
tools.ToolWikiUpdateIssue: operations.RiskWrite,
tools.ToolWikiDeletePage: operations.RiskDestructive,
}
// withoutWikiWriteTools drops the tools that write Wiki state. They execute
// inside the agent engine and so bypass the HTTP KB permission middleware; they
// are removed for shared agents (read-only by contract) and whenever no
// writable wiki KB is in scope.
func withoutWikiWriteTools(allowed []string) []string {
wikiWrites := map[string]bool{
tools.ToolWikiFlagIssue: true,
tools.ToolWikiUpdateIssue: true,
tools.ToolWikiWritePage: true,
tools.ToolWikiReplaceText: true,
tools.ToolWikiRenamePage: true,
tools.ToolWikiDeletePage: true,
}
filtered := make([]string, 0, len(allowed))
for _, name := range allowed {
if !wikiWrites[name] {
filtered = append(filtered, name)
}
}
return filtered
}
// ValidateConfig validates the agent configuration
func (s *agentService) ValidateConfig(config *types.AgentConfig) error {
if config == nil {
return fmt.Errorf("config cannot be nil")
}
if config.MaxIterations < 0 {
config.MaxIterations = types.UnlimitedMaxIterations
} else if config.MaxIterations == 0 {
config.MaxIterations = 5
} else if config.MaxIterations > MAX_ITERATIONS {
return fmt.Errorf("max iterations too high: %d (max %d)", config.MaxIterations, MAX_ITERATIONS)
}
return nil
}
// getKnowledgeBaseInfos retrieves detailed information for knowledge bases.
// kbTenantMap carries the tenant each KB should be queried under (source tenant
// for directly shared KBs); a missing entry falls back to the request tenant.
func (s *agentService) getKnowledgeBaseInfos(ctx context.Context, kbIDs []string, kbTenantMap map[string]uint64) ([]*agent.KnowledgeBaseInfo, error) {
if len(kbIDs) == 0 {
return []*agent.KnowledgeBaseInfo{}, nil
}
kbInfos := make([]*agent.KnowledgeBaseInfo, 0, len(kbIDs))
for _, kbID := range kbIDs {
// Get knowledge base details
kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, kbID)
if err != nil {
logger.Warnf(ctx, "Failed to get knowledge base %s: %v", secutils.SanitizeForLog(kbID), err)
kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{
ID: kbID,
Name: kbID,
Type: "document",
Description: "",
DocCount: 0,
RecentDocs: []agent.RecentDocInfo{},
})
continue
}
// Skip hidden/system-managed knowledge bases (e.g., __chat_history__)
if kb.IsTemporary {
logger.Debugf(ctx, "Skipping temporary knowledge base %s (%s) from prompt", kb.ID, kb.Name)
continue
}
// Document/FAQ listing below is tenant-scoped, so a directly shared KB
// must be queried under its source tenant — the request context belongs
// to the receiving tenant and would silently yield doc_count=0. The
// tenant comes from the SearchTarget that buildSearchTargets already
// authorized; this only widens the metadata query, never the KB set.
metaCtx := ctx
if scopeTenantID := kbTenantMap[kbID]; scopeTenantID != 0 {
metaCtx = context.WithValue(ctx, types.TenantIDContextKey, scopeTenantID)
}
// Get document count and recent documents
docCount := 0
recentDocs := []agent.RecentDocInfo{}
if kb.Type == types.KnowledgeBaseTypeFAQ {
pageResult, err := s.knowledgeService.ListFAQEntries(metaCtx, kbID, &types.Pagination{
Page: 1,
PageSize: 10,
}, nil, 0, "", "", "", nil)
if err == nil && pageResult != nil {
docCount = int(pageResult.Total)
if entries, ok := pageResult.Data.([]*types.FAQEntry); ok {
for _, entry := range entries {
if len(recentDocs) >= 10 {
break
}
recentDocs = append(recentDocs, agent.RecentDocInfo{
ChunkID: entry.ChunkID,
KnowledgeID: entry.KnowledgeID,
KnowledgeBaseID: entry.KnowledgeBaseID,
Title: entry.StandardQuestion,
Type: string(types.ChunkTypeFAQ),
CreatedAt: entry.CreatedAt.Format("2006-01-02"),
FAQStandardQuestion: entry.StandardQuestion,
FAQSimilarQuestions: entry.SimilarQuestions,
FAQAnswers: entry.Answers,
})
}
}
} else if err != nil {
logger.Warnf(ctx, "Failed to list FAQ entries for %s: %v", kbID, err)
}
}
// Fallback to generic knowledge listing when not FAQ or FAQ retrieval failed
if kb.Type != types.KnowledgeBaseTypeFAQ || len(recentDocs) == 0 {
pageResult, err := s.knowledgeService.ListPagedKnowledgeByKnowledgeBaseID(metaCtx, kbID, &types.Pagination{
Page: 1,
PageSize: 10,
}, types.KnowledgeListFilter{
ParseStatus: types.ParseStatusCompleted,
})
if err == nil && pageResult != nil {
docCount = int(pageResult.Total)
// Convert to Knowledge slice
if knowledges, ok := pageResult.Data.([]*types.Knowledge); ok {
for _, k := range knowledges {
if len(recentDocs) >= 10 {
break
}
recentDocs = append(recentDocs, agent.RecentDocInfo{
KnowledgeID: k.ID,
Title: k.Title,
Description: k.Description,
FileName: k.FileName,
Type: k.FileType,
CreatedAt: k.CreatedAt.Format("2006-01-02"),
FileSize: k.FileSize,
})
}
}
}
}
kbType := kb.Type
if kbType == "" {
kbType = "document" // Default type
}
var profile *types.KnowledgeBaseProfile
if kb.GeneratedProfile.HasText() {
profile = kb.GeneratedProfile
}
kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{
ID: kb.ID,
Name: kb.Name,
Type: kbType,
Description: kb.Description,
DocCount: docCount,
Capabilities: kbRetrievalCapabilities(kb),
RecentDocs: recentDocs,
Profile: profile,
})
}
return kbInfos, nil
}
// kbRetrievalCapabilities reports which retrieval surfaces a KB exposes.
// Surfaces are the static facts the hybrid agent prompt consults to pick its
// retrieval strategy — the agent should NOT need to probe this via search.
//
// Returned values are a subset of {"wiki", "chunks"}:
// - "wiki" → the KB has wiki ingestion enabled (wiki_search / wiki_read_page)
// - "chunks" → the KB has vector and/or keyword (BM25) indexing enabled
// (knowledge_search / grep_chunks)
func kbRetrievalCapabilities(kb *types.KnowledgeBase) []string {
if kb == nil {
return nil
}
caps := make([]string, 0, 2)
if kb.IsWikiEnabled() {
caps = append(caps, "wiki")
}
if kb.IsVectorEnabled() || kb.IsKeywordEnabled() {
caps = append(caps, "chunks")
}
return caps
}
// getSelectedDocumentInfos retrieves detailed information for user-selected documents (via @ mention)
// This loads the actual content of the documents to include in the system prompt
// resolveQuestionOriginInfo turns a suggested question's origin into the
// names the runtime context shows. It re-checks the base against this turn's
// search targets rather than trusting the caller, and keeps a document only
// when it belongs to that base.
func (s *agentService) resolveQuestionOriginInfo(
ctx context.Context, origin *types.QuestionOrigin, targets types.SearchTargets,
kbInfos []*agent.KnowledgeBaseInfo,
) *agent.QuestionOriginInfo {
if origin == nil || origin.KnowledgeBaseID == "" || !targets.ContainsKB(origin.KnowledgeBaseID) {
return nil
}
info := &agent.QuestionOriginInfo{
KnowledgeBaseID: origin.KnowledgeBaseID,
KnowledgeBaseName: s.knowledgeBaseName(ctx, origin.KnowledgeBaseID, kbInfos),
}
if origin.KnowledgeID == "" {
return info
}
docs, err := s.getSelectedDocumentInfos(ctx, []string{origin.KnowledgeID})
if err != nil || len(docs) != 1 || docs[0].KnowledgeBaseID != origin.KnowledgeBaseID {
logger.Infof(ctx, "Question origin document %s dropped: not found in knowledge base %s",
secutils.SanitizeForLog(origin.KnowledgeID), secutils.SanitizeForLog(origin.KnowledgeBaseID))
return info
}
info.Document = docs[0]
return info
}
// knowledgeBaseName returns a base's display name, preferring the already
// loaded kbInfos. A base reached only through a document or tag scope is not
// in kbInfos when other bases are selected, so it is looked up directly.
func (s *agentService) knowledgeBaseName(
ctx context.Context, kbID string, kbInfos []*agent.KnowledgeBaseInfo,
) string {
for _, kb := range kbInfos {
if kb != nil && kb.ID == kbID {
return kb.Name
}
}
if s.knowledgeBaseService == nil {
return ""
}
kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, kbID)
if err != nil || kb == nil {
return ""
}
return kb.Name
}
// resolvePageContextInfo turns the page the user has open into what the
// runtime context shows. The config's page context is already narrowed to
// this turn's search targets; this keeps only the parts that exist in that
// base, so the model is never pointed at a document, page or issue it cannot
// find. Parts that fail to resolve are dropped individually.
func (s *agentService) resolvePageContextInfo(
ctx context.Context, page *types.PageContext, targets types.SearchTargets,
kbInfos []*agent.KnowledgeBaseInfo, assistant bool,
) *agent.PageContextInfo {
if page == nil {
return nil
}
info := &agent.PageContextInfo{}
if page.AgentID != "" && s.customAgentService != nil {
agentCtx := ctx
if tenantID := types.CallerFromContext(ctx).TenantID; tenantID != 0 {
agentCtx = types.WithExecutionTenant(ctx, tenantID)
}
if a, err := s.customAgentService.GetAgentByID(agentCtx, page.AgentID); err == nil && a != nil {
info.Agent = &agent.PageContextAgent{ID: a.ID, Name: a.Name}
}
}
if assistant {
s.resolveAssistantPageContext(ctx, page, info)
info.Title = page.Title
info.View = page.View
info.Selection = page.Selection
}
if kbID := page.KnowledgeBaseID; kbID != "" && targets.ContainsKB(kbID) {
s.resolveKnowledgeBasePageContext(ctx, page, targets, kbInfos, info)
}
if info.Empty() {
return nil
}
return info
}
// Bounds on the chat exchange quoted into a page context.
const (
pageContextQuestionRunes = 600
pageContextAnswerRunes = 2000
pageContextMaxReferences = 10
pageContextQuestionLookups = 4
)
// resolveAssistantPageContext adds the page identifier and the settings and
// chat resources only the assistant is shown. Each is dropped unless the
// caller can read it.
func (s *agentService) resolveAssistantPageContext(
ctx context.Context, page *types.PageContext, info *agent.PageContextInfo,
) {
info.Page, info.Section = page.Page, page.Section
tenantID := types.CallerFromContext(ctx).TenantID
if page.ModelID != "" && s.modelService != nil {
if m, err := s.modelService.GetModelByID(ctx, page.ModelID); err == nil && m != nil {
name := m.DisplayName
if name == "" {
name = m.Name
}
info.Model = &agent.PageContextModel{
ID: m.ID, Name: name, Type: string(m.Type), Source: string(m.Source), IsBuiltin: m.IsBuiltin,
}
} else {
logger.Infof(ctx, "Page context model %s dropped: not visible", secutils.SanitizeForLog(page.ModelID))
}
}
if page.MCPServiceID != "" && s.mcpServiceService != nil && tenantID != 0 {
svc, err := s.mcpServiceService.GetMCPServiceByID(ctx, tenantID, page.MCPServiceID)
if err == nil && svc != nil {
info.MCPService = &agent.PageContextMCPService{
ID: svc.ID, Name: svc.Name, Transport: string(svc.TransportType), Enabled: svc.Enabled,
}
} else {
logger.Infof(ctx, "Page context MCP service %s dropped: not visible",
secutils.SanitizeForLog(page.MCPServiceID))
}
}
if page.SessionID != "" && page.MessageID != "" && s.messageService != nil {
info.Message = s.pageContextMessage(ctx, page.SessionID, page.MessageID)
}
}
// pageContextMessage loads the chosen message through the message service,
// which enforces the caller's read access to its session, and quotes the
// question it answered.
func (s *agentService) pageContextMessage(
ctx context.Context, sessionID, messageID string,
) *agent.PageContextMessage {
msg, err := s.messageService.GetMessage(ctx, sessionID, messageID)
if err != nil || msg == nil {
logger.Infof(ctx, "Page context message %s dropped: not readable", secutils.SanitizeForLog(messageID))
return nil
}
out := &agent.PageContextMessage{
SessionID: sessionID, MessageID: msg.ID, Role: msg.Role, AgentID: msg.AgentID,
}
if msg.Role == "user" {
out.Question = truncatePageContextText(msg.Content, pageContextQuestionRunes)
return out
}
out.Answer = truncatePageContextText(msg.Content, pageContextAnswerRunes)
for _, ref := range msg.KnowledgeReferences {
if ref == nil || ref.KnowledgeID == "" {
continue
}
if len(out.References) == pageContextMaxReferences {
break
}
if slices.ContainsFunc(out.References, func(r *agent.PageContextReference) bool {
return r.KnowledgeID == ref.KnowledgeID
}) {
continue
}
title := ref.KnowledgeTitle
if title == "" {
title = ref.KnowledgeFilename
}
out.References = append(out.References, &agent.PageContextReference{
KnowledgeID: ref.KnowledgeID, KnowledgeBaseID: ref.KnowledgeBaseID, Title: title,
})
}
earlier, err := s.messageService.GetMessagesBySessionBeforeTime(
ctx, sessionID, msg.CreatedAt, pageContextQuestionLookups)
if err != nil {
return out
}
for i := len(earlier) - 1; i >= 0; i-- {
if m := earlier[i]; m != nil && m.Role == "user" && m.RequestID == msg.RequestID {
out.Question = truncatePageContextText(m.Content, pageContextQuestionRunes)
break
}
}
return out
}
func truncatePageContextText(s string, limit int) string {
s = strings.TrimSpace(s)
runes := []rune(s)
if len(runes) <= limit {
return s
}
return string(runes[:limit]) + "…"
}
// resolveKnowledgeBasePageContext adds the open knowledge base, after the
// caller checked this turn's search targets reach it, with its document and
// Wiki resources.
func (s *agentService) resolveKnowledgeBasePageContext(
ctx context.Context, page *types.PageContext, targets types.SearchTargets,
kbInfos []*agent.KnowledgeBaseInfo, info *agent.PageContextInfo,
) {
kbID := page.KnowledgeBaseID
info.KnowledgeBaseID = kbID
info.KnowledgeBaseName = s.knowledgeBaseName(ctx, kbID, kbInfos)
if page.KnowledgeID != "" {
docs, err := s.getSelectedDocumentInfos(ctx, []string{page.KnowledgeID})
if err == nil && len(docs) == 1 && docs[0].KnowledgeBaseID == kbID {
info.Document = docs[0]
} else {
logger.Infof(ctx, "Page context document %s dropped: not found in knowledge base %s",
secutils.SanitizeForLog(page.KnowledgeID), secutils.SanitizeForLog(kbID))
}
}
if s.wikiPageService == nil {
return
}
scopes := tools.NewWikiScopesFromSearchTargets(targets, []string{kbID})
if len(scopes) == 0 {
return
}
scope := scopes[0]
// Cache page lookups because the open page and several issue references
// can name the same slug. Failed or out-of-scope lookups stay excluded.
pages := make(map[string]*types.WikiPage)
pageInScope := func(slug string) *types.WikiPage {
if page, ok := pages[slug]; ok {
return page
}
pages[slug] = nil
page, err := s.wikiPageService.GetPageBySlug(ctx, kbID, slug)
if err != nil || page == nil {
return nil
}
allowed, err := tools.WikiPageInScope(ctx, page, scope, s.knowledgeService)
if err != nil {
logger.Warnf(ctx, "Page context wiki scope check failed: %v", err)
return nil
}
if allowed {
pages[slug] = page
}
return pages[slug]
}
if page.WikiSlug != "" {
if wikiPage := pageInScope(page.WikiSlug); wikiPage != nil {
info.WikiPage = &agent.PageContextWikiPage{Slug: wikiPage.Slug, Title: wikiPage.Title}
} else {
logger.Infof(ctx, "Page context wiki page %s dropped: unavailable in scope of knowledge base %s",
secutils.SanitizeForLog(page.WikiSlug), secutils.SanitizeForLog(kbID))
}
}
if len(page.WikiIssueIDs) > 0 {
info.WikiIssues = s.pageContextIssues(ctx, kbID, page.WikiIssueIDs)
if len(scope.KnowledgeIDs) > 0 || len(scope.TagIDs) > 0 {
kept := info.WikiIssues[:0]
for _, issue := range info.WikiIssues {
if pageInScope(issue.Slug) != nil {
kept = append(kept, issue)
}
}
info.WikiIssues = kept
}
}
}
// pageContextIssues keeps the requested issues that exist in kbID, in the
// order the client listed them.
func (s *agentService) pageContextIssues(
ctx context.Context, kbID string, ids []string,
) []*agent.PageContextWikiIssue {
issues, err := s.wikiPageService.ListIssues(ctx, kbID, "", "")
if err != nil {
logger.Warnf(ctx, "Page context issues dropped: list issues of knowledge base %s: %v",
secutils.SanitizeForLog(kbID), err)
return nil
}
byID := make(map[string]*types.WikiPageIssue, len(issues))
for _, issue := range issues {
if issue != nil && issue.KnowledgeBaseID == kbID {
byID[issue.ID] = issue
}
}
kept := make([]*agent.PageContextWikiIssue, 0, len(ids))
for _, id := range ids {
issue, ok := byID[id]
if !ok {
continue
}
kept = append(kept, &agent.PageContextWikiIssue{
ID: issue.ID,
Slug: issue.Slug,
IssueType: issue.IssueType,
Status: issue.Status,
})
}
if len(kept) < len(ids) {
logger.Infof(ctx, "Page context kept %d of %d wiki issues in knowledge base %s",
len(kept), len(ids), secutils.SanitizeForLog(kbID))
}
return kept
}
func (s *agentService) getSelectedDocumentInfos(ctx context.Context, knowledgeIDs []string) ([]*agent.SelectedDocumentInfo, error) {
if len(knowledgeIDs) == 0 {
return []*agent.SelectedDocumentInfo{}, nil
}
// Get tenant ID from context
tenantID := uint64(0)
if tid, ok := types.TenantIDFromContext(ctx); ok {
tenantID = tid
}
// Fetch knowledge metadata (include docs from shared KBs the user has access to)
knowledges, err := s.knowledgeService.GetKnowledgeBatchWithSharedAccess(ctx, tenantID, knowledgeIDs)
if err != nil {
return nil, fmt.Errorf("failed to get knowledge batch: %w", err)
}
// Build map for quick lookup
knowledgeMap := make(map[string]*types.Knowledge)
for _, k := range knowledges {
if k != nil {
knowledgeMap[k.ID] = k
}
}
selectedDocs := make([]*agent.SelectedDocumentInfo, 0, len(knowledgeIDs))
for _, kid := range knowledgeIDs {
k, ok := knowledgeMap[kid]
if !ok {
logger.Warnf(ctx, "Selected knowledge %s not found", kid)
continue
}
docInfo := &agent.SelectedDocumentInfo{
KnowledgeID: k.ID,
KnowledgeBaseID: k.KnowledgeBaseID,
Title: k.Title,
FileName: k.FileName,
FileType: k.FileType,
}
selectedDocs = append(selectedDocs, docInfo)
}
logger.Infof(ctx, "Loaded %d selected documents metadata for prompt", len(selectedDocs))
return selectedDocs, nil
}
func (s *agentService) resolvePinnedMCPServiceInfos(
ctx context.Context,
config *types.AgentConfig,
) []*agent.PinnedMCPServiceInfo {
if len(config.PinnedMCPServiceIDs) == 0 || s.mcpServiceService == nil {
return nil
}
tenantID := uint64(0)
if tid, ok := types.TenantIDFromContext(ctx); ok {
tenantID = tid
}
if tenantID == 0 {
return fallbackPinnedMCPInfos(config.PinnedMCPServiceIDs)
}
services, err := s.mcpServiceService.ListMCPServicesByIDs(ctx, tenantID, config.PinnedMCPServiceIDs)
if err != nil {
logger.Warnf(ctx, "Failed to resolve pinned MCP services: %v", err)
return fallbackPinnedMCPInfos(config.PinnedMCPServiceIDs)
}
byID := make(map[string]*types.MCPService, len(services))
for _, svc := range services {
if svc != nil {
byID[svc.ID] = svc
}
}
result := make([]*agent.PinnedMCPServiceInfo, 0, len(config.PinnedMCPServiceIDs))
for _, id := range config.PinnedMCPServiceIDs {
if id == "" {
continue
}
if svc, ok := byID[id]; ok {
result = append(result, &agent.PinnedMCPServiceInfo{
ID: svc.ID,
Name: svc.Name,
Description: svc.Description,
})
continue
}
result = append(result, &agent.PinnedMCPServiceInfo{ID: id, Name: id})
}
return result
}
func (s *agentService) attachPinnedMCPToolNames(
registry *tools.ToolRegistry,
pinned []*agent.PinnedMCPServiceInfo,
) {
if registry == nil || len(pinned) == 0 {
return
}
byService := tools.MCPToolNamesByServiceID(registry)
for _, info := range pinned {
if info == nil || info.ID == "" {
continue
}
info.ToolNames = append([]string(nil), byService[info.ID]...)
info.Discoverable = registry.HasMCPServer(info.ID)
}
}
func fallbackPinnedMCPInfos(ids []string) []*agent.PinnedMCPServiceInfo {
result := make([]*agent.PinnedMCPServiceInfo, 0, len(ids))
for _, id := range ids {
if id == "" {
continue
}
result = append(result, &agent.PinnedMCPServiceInfo{ID: id, Name: id})
}
return result
}
func (s *agentService) resolvePinnedSkillInfos(config *types.AgentConfig) []*agent.PinnedSkillInfo {
if len(config.PinnedSkillNames) == 0 {
return nil
}
descByName := make(map[string]string)
if len(config.SkillDirs) > 0 {
loader := skills.NewLoader(config.SkillDirs)
if metadata, err := loader.DiscoverSkills(); err == nil {
for _, meta := range metadata {
if meta != nil {
descByName[meta.Name] = meta.Description
}
}
}
}
for _, row := range config.TenantSkills {
if row != nil && row.Name != "" {
descByName[row.Name] = row.Description
}
}
result := make([]*agent.PinnedSkillInfo, 0, len(config.PinnedSkillNames))
for _, name := range config.PinnedSkillNames {
if name == "" {
continue
}
result = append(result, &agent.PinnedSkillInfo{
Name: name,
Description: descByName[name],
})
}
return result
}