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.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
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,
}
}