Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

15.8 KB
Raw Blame
package httpapi

import (
	"context"
	"encoding/json"
	"errors"
	"strings"
	"sync"
	"time"

	"agentflow/internal/application"
	"agentflow/internal/domain"
	"agentflow/internal/mcpclient"
	"agentflow/internal/mcpserver"
)

const (
	agentToolCatalogTTL     = 60 * time.Second
	agentToolSessionMCPName = "agentflow_session"
)

var (
	errAgentToolInvalidSession    = errors.New("invalid agent tool session")
	errAgentToolTerminalCommitted = errors.New("终态已提交,本轮不能再次调用")
	errAgentToolUnknown           = errors.New("unknown tool")
	errAgentToolForbidden         = errors.New("该工具不在当前场景的允许列表中")
)

type agentToolDescriptor struct {
	Name         string
	Description  string
	InputSchema  json.RawMessage
	OutputSchema json.RawMessage
	Annotations  json.RawMessage
	Kind         string
	ServerID     string
	UpstreamName string
	Terminal     bool
}

type agentToolCatalogCache struct {
	mu    sync.Mutex
	items map[string]agentToolCatalogCacheEntry
}

type agentToolCatalogCacheEntry struct {
	tools     []mcpclient.Tool
	expiresAt time.Time
}

var agentToolUpstreamCache = &agentToolCatalogCache{items: map[string]agentToolCatalogCacheEntry{}}

func resetAgentToolCatalogCacheForTest() {
	agentToolUpstreamCache = &agentToolCatalogCache{items: map[string]agentToolCatalogCacheEntry{}}
}

func namespaceAgentTool(kind, name string) string {
	kind = strings.TrimSpace(kind)
	name = strings.TrimSpace(name)
	if kind == "" {
		return name
	}
	return kind + "__" + name
}

func sanitizeAgentToolNamespace(id, name string) string {
	raw := strings.ToLower(strings.TrimSpace(id))
	if raw == "" {
		raw = strings.ToLower(strings.TrimSpace(name))
	}
	var b strings.Builder
	for _, r := range raw {
		if r >= 'a' && r <= 'z' || r >= '0' && r <= '9' {
			b.WriteRune(r)
		} else {
			b.WriteByte('_')
		}
	}
	out := strings.Trim(b.String(), "_")
	for strings.Contains(out, "__") {
		out = strings.ReplaceAll(out, "__", "_")
	}
	switch out {
	case "", "tapd", "gongfeng", "agentflow":
		return "mcp"
	default:
		return out
	}
}

func stripAgentToolServerPrefix(name string) string {
	name = strings.TrimSpace(name)
	for _, prefix := range []string{
		"mcp__" + agentToolSessionMCPName + "__",
		agentToolSessionMCPName + "__",
	} {
		name = strings.TrimPrefix(name, prefix)
	}
	return name
}

func parseNamespacedAgentTool(name string) (kind, tool string, ok bool) {
	name = stripAgentToolServerPrefix(name)
	if name == "" {
		return "", "", false
	}
	kind, tool, found := strings.Cut(name, "__")
	if !found || strings.TrimSpace(kind) == "" || strings.TrimSpace(tool) == "" {
		return "", name, false
	}
	return kind, tool, true
}

func agentToolKindAllowlist(mode AgentToolMode, kind string) map[string]bool {
	out := map[string]bool{}
	for _, name := range agentToolKindAllowlistNames(mode, kind) {
		out[name] = true
	}
	return out
}

func agentToolKindAllowlistNames(mode AgentToolMode, kind string) []string {
	if mode == AgentToolScheduled && kind != "agentflow" {
		return nil
	}
	switch kind {
	case "tapd":
		return []string{
			"lookup_tapd_tool", "lookup_tool_param_schema", "tql_syntax_reference",
			"proxy_execute_tool",
			"stories_get", "stories_list", "bugs_get", "bugs_list",
			"tasks_get", "tasks_list", "comments_get", "comments_list",
		}
	case "gongfeng":
		names := []string{"get_issue_detail", "get_issue_notes"}
		if agentToolAllowsAssistantReads(mode) {
			names = append(names,
				"get_commit_info", "get_commits_list", "get_project_detail",
				"get_repository_tree", "get_blob_content", "get_file_base64_content",
				"search_project_code", "search_project_issues", "search_merge_request",
				"get_merge_request_changes", "compare", "get_file_blame",
				"get_tag_list", "get_branch_list",
			)
		}
		return names
	case "agentflow":
		if mode == AgentToolClarify {
			return []string{"issues_get", "issues_list", "repositories_get", "projects_get"}
		}
		if mode == AgentToolAssistant {
			return agentflowAssistantReadToolNames()
		}
		if mode == AgentToolScheduled {
			return agentflowScheduledToolNames()
		}
		return nil
	default:
		return nil
	}
}

func agentflowNoisyTool(name string) bool {
	switch name {
	case "health_get", "capabilities_get", "openapi_get", "bootstrap_get", "observability_spec_get", "analytics_get", "workflow_metrics_get":
		return true
	// An SSE resume stream, a duplicate of runs_logs_list, and starting a
	// second AI clarification job from inside an agent.
	case "issues_chat_clarify_stream", "runs_logs_download", "issues_chat_clarify", "issues_chat_clarify_cancel", "clarification_chat", "clarification_cancel":
		return true
	default:
		return false
	}
}

func agentflowAssistantReadToolNames() []string {
	var names []string
	for _, op := range application.PublicOperations() {
		if !op.ReadOnly || agentflowNoisyTool(op.Name) {
			continue
		}
		names = append(names, op.Name)
	}
	return names
}

// agentflowAssistantWriteToolNames 返回审批模式放行直连的平台写入工具:
// assisted 提供写入工具并在执行前审查;auto 直接执行。
func agentflowAssistantWriteToolNames(exec assistantExecMode) []string {
	if !exec.AutoWrite {
		return nil
	}
	var names []string
	for _, op := range application.PublicOperations() {
		if op.ReadOnly || agentflowNoisyTool(op.Name) {
			continue
		}
		if exec.ConfirmDangerous && assistantRiskyToolName(op.Name) {
			continue
		}
		names = append(names, op.Name)
	}
	return names
}

// assistantPlatformToolAllowed 校验 assistant 会话允许调用的平台工具:
// 只读工具始终可用,写入工具按审批模式放行(与目录生成一致)。
func assistantPlatformToolAllowed(exec assistantExecMode, name string) bool {
	op, ok := assistantPublicOperations[name]
	if !ok || agentflowNoisyTool(name) {
		return false
	}
	if op.ReadOnly {
		return true
	}
	if !exec.AutoWrite {
		return false
	}
	return !exec.ConfirmDangerous || !assistantRiskyToolName(name)
}

func agentflowScheduledToolNames() []string {
	var names []string
	for _, op := range application.PublicOperations() {
		if agentflowNoisyTool(op.Name) {
			continue
		}
		names = append(names, op.Name)
	}
	return names
}

func agentToolAllowsAssistantReads(mode AgentToolMode) bool {
	return mode == AgentToolAssistant || mode == AgentToolScheduled
}

func agentToolNameAllowed(mode AgentToolMode, kind, tool string) bool {
	tool = strings.TrimSpace(tool)
	if mode == AgentToolReport {
		return false
	}
	if tool == "" {
		return false
	}
	// Conversations and scheduled tasks see every tool of the project's MCPs;
	// a write follows the conversation's approval mode at call time.
	if (mode == AgentToolScheduled || mode == AgentToolAssistant) && kind != "agentflow" {
		return true
	}
	if allowed := agentToolKindAllowlist(mode, kind); len(allowed) > 0 {
		return allowed[tool]
	}
	if kind == "other" {
		return !clarifyMCPWriteName(tool)
	}
	return false
}

func tapdInnerToolAllowed(mode AgentToolMode, name string) bool {
	name = normalizeClarifyTAPDTool(strings.TrimSpace(name))
	if name == "" || name == "proxy_execute_tool" {
		return false
	}
	if mode == AgentToolScheduled || mode == AgentToolAssistant {
		return true
	}
	if !agentToolNameAllowed(mode, "tapd", name) {
		return false
	}
	return !clarifyMCPWriteName(name)
}

func (h *agentToolGateway) buildCatalog(ctx context.Context, session *AgentToolSession) []agentToolDescriptor {
	if session != nil && session.RuntimeMode == domain.AssistantModeWorkspace {
		out := workspaceIntegrationCatalog(session)
		for i, tool := range out {
			if tool.Name == "workbench_workspace_open" {
				out[i] = h.workspaceOpenDescriptorFor(session)
			}
		}
		for _, server := range session.MCPServers {
			if !session.SelectedMCPIDs[server.ID] {
				continue
			}
			kind := classifyClarifyMCP(server)
			if kind == "agentflow" {
				continue
			}
			prefix := kind
			if kind == "other" {
				prefix = sanitizeAgentToolNamespace(server.ID, server.Name)
			}
			tools, err := h.listUpstreamTools(ctx, session, server)
			if err != nil {
				continue
			}
			for _, tool := range tools {
				out = append(out, agentToolDescriptor{Name: namespaceAgentTool(prefix, tool.Name), Description: tool.Description, InputSchema: defaultToolSchema(tool.InputSchema), OutputSchema: tool.OutputSchema, Annotations: tool.Annotations, Kind: kind, ServerID: server.ID, UpstreamName: tool.Name})
			}
		}
		return out
	}
	if session == nil {
		return nil
	}
	session.mu.Lock()
	if session.terminalOnly || session.Mode == AgentToolReport {
		session.mu.Unlock()
		return terminalToolDescriptors(session.Mode, session.ExecMode)
	}
	if len(session.catalog) > 0 {
		out := append([]agentToolDescriptor{}, session.catalog...)
		session.mu.Unlock()
		return out
	}
	session.mu.Unlock()

	out := make([]agentToolDescriptor, 0, 16)
	seen := map[string]bool{}
	for _, server := range session.MCPServers {
		kind := classifyClarifyMCP(server)
		prefix := kind
		if kind == "other" {
			prefix = sanitizeAgentToolNamespace(server.ID, server.Name)
		}
		tools, err := h.listUpstreamTools(ctx, session, server)
		if err != nil {
			logAgentToolEvent("catalog-hide", "mode="+string(session.Mode), "kind="+kind, "err="+truncateRunes(err.Error(), 120))
			session.diagnostics().platform("mcp.upstream_catalog_failed", "外部 MCP 服务 "+server.Name+"("+kind+")拉取工具列表失败:"+err.Error(), session.User)
			continue
		}
		for _, tool := range tools {
			if !agentToolNameAllowed(session.Mode, kind, tool.Name) {
				continue
			}
			name := namespaceAgentTool(prefix, tool.Name)
			if seen[name] {
				continue
			}
			seen[name] = true
			desc := strings.TrimSpace(tool.Description)
			if desc == "" {
				desc = server.Name + " " + tool.Name
			}
			out = append(out, agentToolDescriptor{
				Name:         name,
				Description:  desc,
				InputSchema:  defaultToolSchema(tool.InputSchema),
				OutputSchema: tool.OutputSchema,
				Annotations:  tool.Annotations,
				Kind:         kind,
				ServerID:     server.ID,
				UpstreamName: tool.Name,
			})
		}
	}
	if session.Mode == AgentToolAssistant || session.Mode == AgentToolClarify || session.Mode == AgentToolScheduled {
		for _, name := range agentToolKindAllowlistNames(session.Mode, "agentflow") {
			if session.Mode == AgentToolScheduled && session.ExecMode.DeferSOP && assistantDeferredSOPTool(name) {
				continue
			}
			ns := namespaceAgentTool("agentflow", name)
			if seen[ns] {
				continue
			}
			seen[ns] = true
			op, ok := assistantPublicOperations[name]
			if !ok {
				continue
			}
			schema, _ := json.Marshal(platformToolInputSchema(op))
			out = append(out, agentToolDescriptor{
				Name:         ns,
				Description:  op.Description + " (" + op.Method + " " + op.Path + ")",
				InputSchema:  schema,
				Kind:         "agentflow",
				UpstreamName: name,
			})
		}
	}
	// assisted 的每项写入在执行入口审查;auto 直接执行。
	// confirm 模式目录里没有写工具,模型只能提交草稿。
	if session.Mode == AgentToolAssistant {
		for _, name := range agentflowAssistantWriteToolNames(session.ExecMode) {
			ns := namespaceAgentTool("agentflow", name)
			if seen[ns] {
				continue
			}
			seen[ns] = true
			op, ok := assistantPublicOperations[name]
			if !ok {
				continue
			}
			schema, _ := json.Marshal(platformToolInputSchema(op))
			writePolicy := "平台写入工具(已授权直接执行):"
			if session.ExecMode.ReviewWrites {
				writePolicy = "平台写入工具(执行前独立 AI 审查,未批准时交给用户确认):"
			}
			out = append(out, agentToolDescriptor{
				Name:         ns,
				Description:  writePolicy + op.Description + " (" + op.Method + " " + op.Path + ")",
				InputSchema:  schema,
				Kind:         "agentflow",
				UpstreamName: name,
			})
		}
	}
	if session.Mode == AgentToolAssistant {
		out = append(out, agentToolDescriptor{Name: "workbench_tool_schema", Description: "读取平台工具的准确参数契约。提交写入草稿前先读取对应工具 schema;不要猜字段、路径或参数包装。", InputSchema: json.RawMessage(`{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false}`), Kind: "workbench"})
		if strings.TrimSpace(session.SpaceID) != "" {
			out = append(out, publishArtifactDescriptor(session, false))
		}
	}
	// Platform mode offers only the way into the workspace; everything done in
	// it (files, commands, git, PRs) happens after the handoff.
	if len(mainBotWorkspaceTools(session)) > 0 {
		out = append(out, h.workspaceOpenDescriptorFor(session))
	}
	out = append(out, mainBotBrowserTools(session)...)
	out = append(out, terminalToolDescriptors(session.Mode, session.ExecMode)...)
	session.mu.Lock()
	session.catalog = append([]agentToolDescriptor{}, out...)
	session.mu.Unlock()
	return out
}

func (h *agentToolGateway) listUpstreamTools(ctx context.Context, session *AgentToolSession, server domain.MCPServerDefinition) ([]mcpclient.Tool, error) {
	key := strings.TrimSpace(server.ID) + "|" + strings.TrimSpace(server.URL)
	if tools, ok := agentToolUpstreamCache.get(key); ok {
		return tools, nil
	}
	caller := session.User
	if server.Scope != "personal" && session.Mode == AgentToolClarify {
		caller = h.clarifyMCPUser(domain.Issue{ProjectID: session.ProjectID}, session.User)
	}
	bound, err := bindAssistantMCP(h.repo, server, caller)
	if err != nil {
		return nil, err
	}
	client := mcpclient.New(bound.URL, bound.Headers).WithTimeout(20 * time.Second)
	tools, err := client.ListToolsContext(ctx)
	if err != nil {
		return nil, err
	}
	agentToolUpstreamCache.put(key, tools)
	return tools, nil
}

func (c *agentToolCatalogCache) get(key string) ([]mcpclient.Tool, bool) {
	c.mu.Lock()
	defer c.mu.Unlock()
	item, ok := c.items[key]
	if !ok || time.Now().After(item.expiresAt) {
		return nil, false
	}
	return item.tools, true
}

func (c *agentToolCatalogCache) put(key string, tools []mcpclient.Tool) {
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.items == nil {
		c.items = map[string]agentToolCatalogCacheEntry{}
	}
	c.items[key] = agentToolCatalogCacheEntry{tools: tools, expiresAt: time.Now().Add(agentToolCatalogTTL)}
}

func defaultToolSchema(raw json.RawMessage) json.RawMessage {
	if len(raw) == 0 || string(raw) == "null" {
		return json.RawMessage(`{"type":"object"}`)
	}
	return raw
}

func platformToolInputSchema(op application.Operation) map[string]any {
	return mcpserver.ToolInputSchema(op)
}

func lookupAgentTool(catalog []agentToolDescriptor, name string) (agentToolDescriptor, bool) {
	name = stripAgentToolServerPrefix(name)
	for _, item := range catalog {
		if item.Name == name {
			return item, true
		}
	}
	return agentToolDescriptor{}, false
}

func redactAgentToolResult(text string, user domain.User) string {
	text = redactAssistantSecrets(strings.TrimSpace(text), user)
	return redactAuthorizationValues(text)
}

func redactAuthorizationValues(text string) string {
	if text == "" {
		return text
	}
	var b strings.Builder
	lower := strings.ToLower(text)
	start := 0
	for {
		idx := strings.Index(lower[start:], "authorization")
		if idx < 0 {
			b.WriteString(text[start:])
			break
		}
		idx += start
		b.WriteString(text[start:idx])
		rest := text[idx:]
		colon := strings.IndexAny(rest, ":=")
		if colon < 0 || colon > 24 {
			b.WriteString("authorization")
			start = idx + len("authorization")
			continue
		}
		b.WriteString(rest[:colon+1])
		cursor := colon + 1
		for cursor < len(rest) && (rest[cursor] == ' ' || rest[cursor] == '"' || rest[cursor] == '\'') {
			b.WriteByte(rest[cursor])
			cursor++
		}
		b.WriteString("[redacted]")
		for cursor < len(rest) && rest[cursor] != '"' && rest[cursor] != '\'' && rest[cursor] != ',' && rest[cursor] != '}' && rest[cursor] != '\n' && rest[cursor] != '\r' {
			cursor++
		}
		start = idx + cursor
		if start > len(text) {
			break
		}
	}
	return b.String()
}

func mcpToolTextResult(text string, isError bool) map[string]any {
	if !strings.HasSuffix(text, "\n") {
		text += "\n"
	}
	return map[string]any{
		"content": []map[string]any{{"type": "text", "text": text}},
		"isError": isError,
	}
}