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.

12.8 KB
Raw Blame
package httpapi

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"
	"path"
	"path/filepath"
	"regexp"
	"sort"
	"strings"

	"agentflow/internal/domain"
	"agentflow/internal/runtime"
)

// roleSubagent is a mentioned role with the rules and skills it is bound to,
// resolved for the conversation's project the way an SOP node resolves them.
type roleSubagent struct {
	Role       domain.AgentDefinition
	Rules      []domain.RuleDefinition
	Skills     []domain.SkillDefinition
	SkillFiles map[string]map[string][]byte
}

// resolveRoleSubagent attaches the role's own rules and skills. MCP servers
// are not attached: chat only proxies the project's HTTP MCP through the
// session gateway and never starts stdio commands on the control plane.
func (h *assistantHandlers) resolveRoleSubagent(role domain.AgentDefinition, projectID string, userID int64) roleSubagent {
	out := roleSubagent{Role: role}
	if h.engine == nil {
		return out
	}
	assets := h.engine.RoleAssets(role, projectID, userID)
	bound := map[string]bool{}
	for _, id := range role.Rules {
		bound[id] = true
	}
	// The knowledge toggle adds a usage rule for an MCP chat does not mount.
	for _, rule := range assets.Rules {
		if bound[rule.ID] {
			out.Rules = append(out.Rules, rule)
		}
	}
	out.Skills, out.SkillFiles = assets.Skills, assets.SkillFiles
	return out
}

// roleSubagentName is the native subagent type a mentioned role runs as.
func roleSubagentName(id string) string {
	name := strings.Trim(roleSubagentUnsafe.ReplaceAllString(strings.ToLower(id), "-"), "-")
	return "role-" + name
}

var roleSubagentUnsafe = regexp.MustCompile(`[^a-z0-9]+`)

// roleAgentFile renders a role as a CodeBuddy agent definition: frontmatter
// with the subagent name, description and the role's skills (already written
// to the CLI home), then the role's brief followed by its rules.
func roleAgentFile(item roleSubagent) string {
	return renderRoleAgentFile(item, false)
}

func renderRoleAgentFile(item roleSubagent, workspace bool) string {
	role := item.Role
	description := strings.TrimSpace(role.Description)
	if description == "" {
		description = role.Name
	}
	quote := func(v string) string {
		raw, _ := json.Marshal(v)
		return string(raw)
	}
	var b strings.Builder
	b.WriteString("---\nname: " + roleSubagentName(role.ID) + "\n")
	b.WriteString("description: " + quote("角色「"+role.Name+"」:"+description) + "\n")
	// Submitting the reply ends Main Bot's whole turn with the subagent's
	// text; a write that needs the user's confirmation goes back to Main Bot.
	b.WriteString("disallowedTools:\n")
	for _, tool := range subagentBlockedTools {
		b.WriteString("  - " + tool + "\n")
	}
	if len(item.Skills) > 0 {
		b.WriteString("skills:\n")
		for _, skill := range item.Skills {
			b.WriteString("  - " + runtime.SkillName(skill.ID) + "\n")
		}
	}
	b.WriteString("---\n")
	b.WriteString("你是「" + role.Name + "」,由 Main Bot 派发来完成一项任务。按以下角色定义工作,完成后简要汇报做了什么、改了哪些文件、结果如何;做不到时如实说明原因。\n\n")
	b.WriteString(subagentChatNotes)
	b.WriteString(subagentRolePrompt(role.Prompt) + subagentRules(item.Rules) + "\n")
	// The body is rendered by the CLI on the control plane like a skill.
	if workspace {
		return b.String()
	}
	return runtime.InertCLIText(b.String())
}

// subagentChatNotes tells a role subagent what Main Bot's system prompt tells
// Main Bot, which a subagent does not receive: where the code is, and that a
// chat dispatch is not an SOP node.
// subagentBlockedTools are Main Bot's alone: submitting the reply ends the
// whole turn, and opening a workspace switches the one Main Bot is bound to.
var subagentBlockedTools = []string{
	"mcp__agentflow_session__" + submitAssistantReplyTool,
	"mcp__agentflow_session__workbench_workspace_open",
}

const subagentChatNotes = `## 在对话里工作

- 这是对话里的派发,不是 SOP 节点:以 Main Bot 交给你的任务为准。角色定义里要求的交付物文件照常写到工作区根目录下对应的路径(如 archive.md),你结束后平台会自动收集并展示给用户,不用再附加;只有 Main Bot 的任务明确说不要写文件时才不写。产物校验脚本、门禁命令和 {{…}} 输入输出是 SOP 节点才有的,对话里不适用。
- 当前是平台模式,CLI 在会话绑定机器的缓存目录内运行,不能在这里搜索或修改项目代码。需要读写代码或跑命令时请向 Main Bot 汇报,让它先打开工作区并交接模式,再派发编程任务。你不能打开或切换工作区(workbench_workspace_open 对你不可用),也不能切换运行模式。SOP 执行中的文件只能由 Main Bot 查看。
- 写操作被拒绝、提示需要用户确认或放入 drafts 时,不要自己提交回复或草稿:在汇报里写明要做的操作和完整参数,由 Main Bot 交给用户确认。

`

// labelRoleSubagent names the role an Agent dispatch runs as, so the UI shows
// the role instead of its subagent type.
func labelRoleSubagent(event assistantStreamEvent, roles []roleSubagent) assistantStreamEvent {
	if event.Subagent == "" {
		return event
	}
	for _, role := range roles {
		if roleSubagentName(role.Role.ID) == event.Subagent {
			event.Role = role.Role.Name
			break
		}
	}
	return event
}

// roleAgentIDs maps each subagent type to the agent ID of its latest finished
// dispatch in the stored transcript, so a later turn can resume it.
func roleAgentIDs(messages []domain.AssistantMessage) map[string]string {
	out := map[string]string{}
	for _, message := range messages {
		types := map[string]string{}
		for _, event := range message.Activity {
			if event.Kind == "tool" && event.Subagent != "" && event.ID != "" {
				types[event.ID] = event.Subagent
			}
			if event.Kind == "toolDone" && event.AgentID != "" && !event.Failed {
				if kind := types[event.ID]; kind != "" {
					out[kind] = event.AgentID
				}
			}
		}
	}
	return out
}

// subagentRules renders rules like an SOP node's agent-system.md, highest
// priority first.
func subagentRules(rules []domain.RuleDefinition) string {
	if len(rules) == 0 {
		return ""
	}
	sorted := append([]domain.RuleDefinition(nil), rules...)
	sort.SliceStable(sorted, func(i, j int) bool { return sorted[i].Priority > sorted[j].Priority })
	var b strings.Builder
	b.WriteString("\n\n## Rules")
	for _, rule := range sorted {
		b.WriteString("\n\n### " + rule.Name + "\n" + rule.Content)
	}
	return b.String()
}

// subagentRolePrompt shows a role's run brief to a chat subagent, where no
// run is bound, so runtime placeholders such as {{input}} have no value.
func subagentRolePrompt(prompt string) string {
	return rolePromptPlaceholder.ReplaceAllString(strings.TrimSpace(prompt), "(运行时提供)")
}

var rolePromptPlaceholder = regexp.MustCompile(`\{\{[^{}]+\}\}`)

// writeConversationAssets rewrites the conversation's CLI home each turn:
// skills holds the project's own skills and the shared skills, plus those of
// its roles and the mentioned ones, and agents holds one subagent per role,
// so Main Bot and its subagents use them natively. Every shared skill is
// installed on every turn, including a conversation without a project, so a
// scheduled task can call one without mentioning it; it brings only its
// SKILL.md unless it is also the project's own, bound or mentioned. A turn
// with no project, no shared skills and no mentioned roles gets empty
// directories.
func (h *assistantHandlers) writeConversationAssets(root string, req assistantRequest) error {
	if err := runtime.ValidateConversationRoot(root); err != nil {
		return err
	}
	if err := writeConversationAttachments(root, req); err != nil {
		return err
	}
	var skills []domain.SkillDefinition
	files := map[string]map[string][]byte{}
	seen := map[string]bool{}
	add := func(skill domain.SkillDefinition, contents map[string][]byte) {
		if seen[skill.ID] {
			return
		}
		seen[skill.ID] = true
		skills = append(skills, skill)
		if len(contents) > 0 {
			files[skill.ID] = contents
		}
	}
	project := strings.TrimSpace(req.ProjectID)
	load := func(skill domain.SkillDefinition) {
		var contents map[string][]byte
		if len(skill.FileRefs) > 0 {
			contents = h.repo.SkillFileContents(skill.ID)
		}
		add(skill, contents)
	}
	var shared []domain.SkillDefinition
	for _, skill := range h.repo.Skills() {
		switch {
		case project != "" && skill.ProjectID == project:
			load(skill)
		case skill.Shared:
			shared = append(shared, skill)
		}
	}
	for _, role := range req.roles {
		for _, skill := range role.Skills {
			add(skill, role.SkillFiles[skill.ID])
		}
	}
	for _, skill := range req.skills {
		load(skill)
	}
	// A shared skill nobody bound or mentioned gets only its SKILL.md: its
	// other files would be copied into every conversation on the platform
	// each turn. Mentioning it or binding it to a role installs them.
	sort.Slice(shared, func(i, j int) bool { return shared[i].ID < shared[j].ID })
	for _, skill := range shared {
		if seen[skill.ID] {
			continue
		}
		var contents map[string][]byte
		if data, ok := h.repo.SkillFileContent(skill.ID, "SKILL.md"); ok {
			contents = map[string][]byte{"SKILL.md": data}
		}
		skill.Files = nil
		skill.FileRefs = nil
		add(skill, contents)
	}
	engine, _ := assistantModelEngine(req.Model)
	home := filepath.Join(root, "home", assistantEngineConfigDir(engine))
	if runtime.IsAgentCLI(engine) {
		home = filepath.Join(root, "home", ".agents")
	}
	if engine == runtime.AgentCLIPi {
		home = filepath.Join(root, "home", ".pi", "agent")
	}
	if engine == runtime.AgentCLIAntigravity {
		home = filepath.Join(root, "home", ".gemini", "config")
	}
	writer := runtime.WriteInertSkillTree
	if req.workspaceMode {
		writer = runtime.WriteSkillTree
	}
	if _, err := writer(filepath.Join(home, "skills"), skills, files); err != nil {
		return err
	}
	agents := filepath.Join(home, "agents")
	if err := os.RemoveAll(agents); err != nil {
		return err
	}
	if len(req.roles) == 0 {
		return nil
	}
	if err := os.MkdirAll(agents, 0o755); err != nil {
		return err
	}
	for _, role := range req.roles {
		name := roleSubagentName(role.Role.ID)
		if err := os.WriteFile(filepath.Join(agents, name+".md"), []byte(conversationRoleAgentFile(role, req.workspaceMode)), 0o644); err != nil {
			return err
		}
	}
	return nil
}

type roleDeliverableKey struct{}

// collectRoleDeliverables does for a finished role dispatch what an SOP node
// does after it runs: the files the role's artifactOutputs name are read
// from the conversation workspace and attached to this turn's reply. Each
// one becomes a step under the dispatch, so the subagent's 产物 tab lists it;
// a required file that is missing is a failed step. Nothing is retried.
func (h *assistantHandlers) collectRoleDeliverables(ctx context.Context, s *AgentToolSession, dispatchID, subagent string, roles []roleSubagent) []assistantStreamEvent {
	if s == nil || dispatchID == "" || subagent == "" || s.workspaceRun() == "" {
		return nil
	}
	var role *domain.AgentDefinition
	for i := range roles {
		if roleSubagentName(roles[i].Role.ID) == subagent {
			role = &roles[i].Role
			break
		}
	}
	if role == nil || len(role.ArtifactOutputs) == 0 {
		return nil
	}
	gateway := &agentToolGateway{deps: h.deps}
	ctx = context.WithValue(ctx, roleDeliverableKey{}, true)
	var out []assistantStreamEvent
	for i, contract := range role.ArtifactOutputs {
		rel := path.Clean(strings.TrimPrefix(strings.ReplaceAll(strings.TrimSpace(contract.Path), "\\", "/"), "./"))
		if rel == "." || rel == "" || path.IsAbs(rel) || strings.HasPrefix(rel, "..") {
			continue
		}
		id := fmt.Sprintf("deliverable-%s-%d", dispatchID, i)
		_, err := gateway.callMainBotWorkspace(ctx, s, workspaceAttachInternal, map[string]any{"path": rel})
		if err != nil && !contract.Required {
			continue
		}
		step := assistantStreamEvent{Kind: "tool", ID: id, Parent: dispatchID, Tool: "交付物", Detail: path.Base(rel), Text: "已收集交付物 · " + rel}
		done := assistantStreamEvent{Kind: "toolDone", ID: id, Parent: dispatchID}
		if err != nil {
			step.Text = "缺少必需交付物 · " + rel
			done.Failed = true
			log.Printf("assistant deliverable session=%s role=%s path=%s: %v", s.ChatSessionID, role.ID, rel, err)
		}
		out = append(out, step, done)
	}
	return out
}

func conversationRoleAgentFile(role roleSubagent, workspace bool) string {
	body := renderRoleAgentFile(role, workspace)
	if !workspace {
		return body
	}
	body = strings.Replace(body, subagentChatNotes, "你和 Main Bot 在同一工作区,沙箱内的文件和命令直接执行;平台写入以及 git push、gh pr create 等写入外部系统的命令遵守当前审批模式。不能打开或切换工作区,不能切回平台模式;需要切换时向 Main Bot 汇报。\n", 1)
	body = strings.Replace(body, "  - mcp__agentflow_session__workbench_workspace_open\n", "  - mcp__agentflow_session__workbench_workspace_open\n  - mcp__agentflow_session__workbench_platform_mode\n", 1)
	return body
}