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 (
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"encoding/base64"
"encoding/hex"
"fmt"
"io"
"net/http"
"os"
"slices"
"strings"
stdsync "sync"
"time"
"agentflow/internal/domain"
"agentflow/internal/repo"
"github.com/gin-gonic/gin"
)
// CLI Runner connection API (cli-connect.md).
//
// Runner-agent endpoints authenticate with their own credentials and are
// therefore exempt from user access auth: register uses the shared bootstrap
// token, everything else uses the runner's session token. Management
// endpoints (list runners, create/cancel tasks) stay behind user auth.
//
// Task reliability never depends on a live connection: the task table is the
// queue, the long poll is only a wakeup path, and WebSocket is the low-latency
// control path.
//
// 路由(gin 注册,供 server.go 参考):
//
// 管理面(userAccessAuth 保护):
//
// g.GET("/api/runners", h.runners)
// g.POST("/api/runners/register", h.runnerRegister)
// g.POST("/api/runners/deregister", h.runnerDeregister)
// g.POST("/api/runners/disconnect", h.runnerDisconnect)
// g.POST("/api/runners/bind-codes", h.issueRunnerBindCode)
// g.GET("/api/runners/default", h.runnerDefault)
// g.DELETE("/api/runners/:id", h.runnerRemove)
// g.PUT("/api/runners/default", h.runnerDefaultSet)
// g.PUT("/api/runners/runtimes", h.runnerRuntimeStatus)
// g.POST("/api/runners/runtimes", h.runnerRuntimeStatus)
// g.GET("/api/runners/tasks", h.runnerTasksCollection)
// g.POST("/api/runners/tasks", h.runnerTasksCollection)
// g.POST("/api/runners/tasks/claim", h.runnerTaskClaim)
// g.GET("/api/runners/tasks/:id", h.runnerTaskGet)
// g.POST("/api/runners/tasks/:id/cancel", h.runnerTaskCancel)
// g.GET("/api/runners/tasks/:id/events", h.runnerTaskEventsOut)
// g.POST("/api/runners/tasks/:id/events", h.runnerTaskEventsIngest)
// g.POST("/api/runners/tasks/:id/start", h.runnerTaskStart)
// g.POST("/api/runners/tasks/:id/lease/renew", h.runnerTaskLeaseRenew)
// g.POST("/api/runners/tasks/:id/complete", h.runnerTaskComplete)
// g.GET("/api/runners/tasks/:id/control", h.runnerTaskControl)
//
// 机器面 /runners/*(豁免 userAccessAuth,runner 使用自有凭证):
//
// g.GET("/runners/install.sh", serveBindCLIScript)(定义在 server.go)
// g.GET("/runners/agentflow-runner", serveRunnerBinary)
// g.GET("/runners/health", h.health)(定义在 server.go)
// g.POST("/runners/register", h.runnerRegister)
// g.POST("/runners/deregister", h.runnerDeregister)
// g.POST("/runners/disconnect", h.runnerDisconnect)
// g.POST("/runners/heartbeat", h.runnerHeartbeat)
// g.POST("/runners/tasks/claim", h.runnerTaskClaim)
// g.POST("/runners/tasks/:id/start", h.runnerTaskStart)
// g.POST("/runners/tasks/:id/lease/renew", h.runnerTaskLeaseRenew)
// g.POST("/runners/tasks/:id/events", h.runnerTaskEventsIngest)
// g.POST("/runners/tasks/:id/complete", h.runnerTaskComplete)
// g.GET("/runners/tasks/:id/control", h.runnerTaskControl)
const (
runnerLongPollDefault = 30 * time.Second
runnerDBPollDefault = time.Second
runnerOfflineThreshold = 90 * time.Second
runnerTaskLeaseTTL = 120 * time.Second
runnerSweepInterval = 15 * time.Second
runnerSessionTokenPrefix = "afr_"
runnerSessionTTL = 30 * 24 * time.Hour
)
type runnersHandlers struct {
*deps
runnerWaiters *runnerWaiterRegistry
runnerControls *runnerControlHub
assistant *assistantHandlers
runnerBindMu stdsync.Mutex
runnerBindCodes map[string]runnerBindCode
}
// ---------- waiter registry ----------
// runnerWaiterRegistry wakes long-polling runners when a task may have become
// claimable. Notify is only "there might be work": the DB claim is still the
// single source of truth, so a lost or spurious wakeup is harmless.
type runnerWaiterRegistry struct {
mu stdsync.Mutex
nextID int64
waiters map[int64]*runnerWaiter
}
type runnerWaiter struct {
id int64
providers []string
ch chan struct{}
}
func newRunnerWaiterRegistry() *runnerWaiterRegistry {
return &runnerWaiterRegistry{waiters: map[int64]*runnerWaiter{}}
}
func (r *runnerWaiterRegistry) register(providers []string) *runnerWaiter {
r.mu.Lock()
defer r.mu.Unlock()
r.nextID++
w := &runnerWaiter{id: r.nextID, providers: providers, ch: make(chan struct{}, 1)}
r.waiters[w.id] = w
return w
}
func (r *runnerWaiterRegistry) unregister(w *runnerWaiter) {
r.mu.Lock()
defer r.mu.Unlock()
delete(r.waiters, w.id)
}
func (r *runnerWaiterRegistry) notify(providers []string) {
r.mu.Lock()
defer r.mu.Unlock()
for _, w := range r.waiters {
if !w.accepts(providers) {
continue
}
select {
case w.ch <- struct{}{}:
default:
}
}
}
// accepts reports whether any of providers matches one the waiter is polling
// for, compared case-insensitively.
func (w *runnerWaiter) accepts(providers []string) bool {
return slices.ContainsFunc(providers, func(p string) bool {
return slices.ContainsFunc(w.providers, func(v string) bool { return strings.EqualFold(v, p) })
})
}
// ---------- background sweeper ----------
// startRunnerSweeper recovers tasks whose lease expired (runner slept or
// crashed) and marks silent runners offline. Both thresholds follow the
// defaults recommended in cli-connect.md.
func (h *runnersHandlers) startRunnerSweeper() {
go func() {
ticker := time.NewTicker(runnerSweepInterval)
defer ticker.Stop()
for range ticker.C {
now := time.Now().UTC()
h.repo.MarkOfflineRunners(runnerOfflineThreshold, now)
recovered, err := h.repo.ExpireRunnerTasks(now)
if err != nil {
continue
}
for _, task := range recovered {
h.engine.NotifyRunnerTaskChanged(task.ID)
}
}
}()
}
// ---------- authentication ----------
func runnerBootstrapToken() string {
return strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_BOOTSTRAP_TOKEN"))
}
func constantTimeEqual(a, b string) bool {
return subtle.ConstantTimeCompare([]byte(a), []byte(b)) == 1
}
// runnerFromSession resolves the Bearer session token issued at registration.
func (h *runnersHandlers) runnerFromSession(r *http.Request) (domain.Runner, bool) {
raw, ok := bearerToken(r)
if !ok || !strings.HasPrefix(raw, runnerSessionTokenPrefix) {
return domain.Runner{}, false
}
sum := sha256.Sum256([]byte(raw))
return h.repo.RunnerSessionByHash(hex.EncodeToString(sum[:]))
}
// runnerSessionAuth resolves the runner session for task-plane handlers and
// writes the 401 response when the credential is missing or invalid.
func (h *runnersHandlers) runnerSessionAuth(c *gin.Context) (domain.Runner, bool) {
runner, ok := h.runnerFromSession(c.Request)
if !ok {
c.Header("WWW-Authenticate", `Bearer realm="AgentFlow Runner"`)
c.JSON(http.StatusUnauthorized, map[string]string{"error": "invalid runner session"})
}
return runner, ok
}
func newRunnerSessionToken() (string, string, error) {
raw := make([]byte, 32)
if _, err := rand.Read(raw); err != nil {
return "", "", err
}
plain := runnerSessionTokenPrefix + base64.RawURLEncoding.EncodeToString(raw)
sum := sha256.Sum256([]byte(plain))
return plain, hex.EncodeToString(sum[:]), nil
}
// ---------- management endpoints ----------
// 路由: g.GET("/api/runners", h.runners)
func (h *runnersHandlers) runners(c *gin.Context) {
list := domain.PublicRunners(h.repo.Runners())
// The personal 执行器 page lists only machines bound to the current user.
if strings.TrimSpace(c.Query("mine")) == "1" {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后查看我的执行器"})
return
}
mine := make([]domain.Runner, 0, len(list))
for _, item := range list {
if item.OwnerUserID == user.ID {
mine = append(mine, item)
}
}
list = mine
}
c.JSON(http.StatusOK, list)
}
// runnerDefault returns the user's default execution machine (执行机器).
// 路由: g.GET("/api/runners/default", h.runnerDefault)
func (h *runnersHandlers) runnerDefault(c *gin.Context) {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后管理执行机器"})
return
}
runnerID := h.repo.DefaultRunner(user.ID)
runner, found := h.repo.Runner(runnerID)
var poolConfigured bool
var poolOnline int
if h.engine != nil {
poolConfigured, poolOnline = h.engine.CloudPoolStatus()
}
c.JSON(http.StatusOK, map[string]any{
"runnerId": runnerID,
"runner": runner,
"online": found && runner.Status == domain.RunnerStatusOnline,
"cloudPool": map[string]any{"configured": poolConfigured, "online": poolOnline},
// minRunnerVersion lets the runners page disable「设为默认」with the
// same rule PUT /api/runners/default enforces.
"minRunnerVersion": domain.RunnerVersionDefaultSelection,
})
}
// runnerRemove unbinds one of the caller's own offline machines, for a machine
// that is gone for good and can no longer deregister itself.
// 路由: g.DELETE("/api/runners/:id", h.runnerRemove)
func (h *runnersHandlers) runnerRemove(c *gin.Context) {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后管理执行机器"})
return
}
runner, found := h.repo.Runner(strings.TrimSpace(c.Param("id")))
if !found {
c.JSON(http.StatusOK, map[string]bool{"ok": true})
return
}
if runner.OwnerUserID != user.ID {
c.JSON(http.StatusForbidden, map[string]string{"error": "只能移除自己绑定的执行机器"})
return
}
if runner.Status == domain.RunnerStatusOnline {
c.JSON(http.StatusConflict, map[string]string{"error": "机器在线,请先在该机器上执行卸载命令,或停止后再移除"})
return
}
if err := h.repo.DeregisterRunner(runner.ID, time.Now().UTC()); err != nil && err != repo.ErrRunnerNotFound {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// runnerRunLimitSet sets how many top-level SOP runs one of the caller's own
// machines may hold at once. 0 clears the limit (unlimited, the default).
// 路由: g.PUT("/api/runners/:id/run-limit", h.runnerRunLimitSet)
func (h *runnersHandlers) runnerRunLimitSet(c *gin.Context) {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后管理执行机器"})
return
}
var input struct {
RunLimit *int `json:"runLimit"`
}
if !decode(c, &input) {
return
}
if input.RunLimit == nil || *input.RunLimit < 0 || *input.RunLimit > repo.MaxRunnerRunLimit {
c.JSON(http.StatusBadRequest, map[string]string{"error": fmt.Sprintf("runLimit 需为 0-%d 的整数,0 表示不限制", repo.MaxRunnerRunLimit)})
return
}
runner, found := h.repo.Runner(strings.TrimSpace(c.Param("id")))
if !found {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
if runner.OwnerUserID == 0 || runner.OwnerUserID != user.ID {
c.JSON(http.StatusForbidden, map[string]string{"error": "只能设置自己绑定的执行机器"})
return
}
if err := h.repo.SetRunnerRunLimit(runner.ID, *input.RunLimit); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
runner, _ = h.repo.Runner(runner.ID)
c.JSON(http.StatusOK, domain.PublicRunner(runner))
}
// runnerDefaultSet selects or clears the user's default execution machine.
// Only online machines bound to the requesting user, at or above
// RunnerVersionDefaultSelection, can be selected.
// 路由: g.PUT("/api/runners/default", h.runnerDefaultSet)
func (h *runnersHandlers) runnerDefaultSet(c *gin.Context) {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后管理执行机器"})
return
}
var input struct {
RunnerID string `json:"runnerId"`
}
if !decode(c, &input) {
return
}
runnerID := strings.TrimSpace(input.RunnerID)
if runnerID != "" {
runner, found := h.repo.Runner(runnerID)
if !found {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
if runner.OwnerUserID != user.ID {
c.JSON(http.StatusForbidden, map[string]string{"error": "只能选择自己绑定的执行机器"})
return
}
if reason := runner.DefaultSelectionBlocker(); reason != "" {
c.JSON(http.StatusConflict, map[string]string{"error": reason})
return
}
}
if err := h.repo.SetDefaultRunner(user.ID, runnerID, time.Now().UTC()); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
if runnerID == "" {
c.JSON(http.StatusOK, map[string]any{"runnerId": "", "message": "已切回云端执行"})
} else {
c.JSON(http.StatusOK, map[string]any{"runnerId": runnerID, "message": "已设为默认执行机器,你的任务和沙箱将在这台机器上执行"})
}
}
// runnerRuntimeStatus updates per-provider runtime status/auth mode. The
// trailing sub-path of the legacy /api/runners/runtimes/... form was always
// ignored, so this is registered as a flat PUT|POST route.
// 路由: g.PUT("/api/runners/runtimes", h.runnerRuntimeStatus)
//
// g.POST("/api/runners/runtimes", h.runnerRuntimeStatus)
func (h *runnersHandlers) runnerRuntimeStatus(c *gin.Context) {
var input struct {
RunnerID string `json:"runnerId"`
Provider string `json:"provider"`
Status string `json:"status"`
AuthMode string `json:"authMode"`
}
if !decode(c, &input) {
return
}
input.RunnerID = strings.TrimSpace(input.RunnerID)
input.Provider = strings.TrimSpace(input.Provider)
input.Status = strings.TrimSpace(input.Status)
input.AuthMode = strings.TrimSpace(input.AuthMode)
if input.RunnerID == "" || input.Provider == "" {
c.JSON(http.StatusBadRequest, map[string]string{"error": "runnerId 和 provider 不能为空"})
return
}
if input.Status == "" && input.AuthMode == "" {
c.JSON(http.StatusBadRequest, map[string]string{"error": "status 和 authMode 至少提供一个"})
return
}
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后管理执行机器"})
return
}
runner, found := h.repo.Runner(input.RunnerID)
if !found {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
if runner.OwnerUserID != user.ID {
c.JSON(http.StatusForbidden, map[string]string{"error": "只能管理自己绑定的执行机器"})
return
}
now := time.Now().UTC()
if input.Status != "" {
if err := h.repo.SetRunnerRuntimeStatus(input.RunnerID, input.Provider, input.Status, now); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
return
}
}
if input.AuthMode != "" {
if err := h.repo.SetRunnerRuntimeAuthMode(input.RunnerID, input.Provider, input.AuthMode, now); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusNotFound, map[string]string{"error": "执行机器不存在"})
return
}
c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
return
}
}
runner, _ = h.repo.Runner(input.RunnerID)
c.JSON(http.StatusOK, domain.PublicRunner(runner))
}
// runnerDisconnect marks a daemon offline without deleting its identity,
// session, or the user's default-runner selection. A normal service restart
// therefore reconnects with the existing session instead of needing a new
// one-time bind code. Explicit uninstall continues to use deregister.
// 路由: g.POST("/api/runners/disconnect", h.runnerDisconnect)
//
// g.POST("/runners/disconnect", h.runnerDisconnect)
func (h *runnersHandlers) runnerDisconnect(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
if err := h.repo.MarkRunnerOffline(runner.ID, time.Now().UTC()); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusOK, map[string]bool{"ok": true})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// ---------- one-time bind codes ----------
// runnerBindCodeTTL keeps the copy-pasted onboarding command valid long
// enough to reach a terminal without leaving a standing credential behind.
const runnerBindCodeTTL = 10 * time.Minute
const runnerBindCodePrefix = "bind-"
type runnerBindCode struct {
userID int64
expiresAt time.Time
}
// consumeRunnerBindCode resolves and burns a one-time bind code generated by
// the 执行器 page. Burning on match keeps codes strictly single-use: a leaked
// command cannot be replayed, and the user simply refreshes the page for a
// new one.
func (h *runnersHandlers) consumeRunnerBindCode(code string) (int64, bool) {
code = strings.TrimSpace(code)
if !strings.HasPrefix(code, runnerBindCodePrefix) {
return 0, false
}
h.runnerBindMu.Lock()
defer h.runnerBindMu.Unlock()
now := time.Now().UTC()
entry, exists := h.runnerBindCodes[code]
if !exists || !entry.expiresAt.After(now) {
if exists {
delete(h.runnerBindCodes, code)
}
return 0, false
}
delete(h.runnerBindCodes, code)
return entry.userID, true
}
// newRunnerBindCode issues a one-time code that registers the machine under
// the requesting user. Called from the 执行器 page; requires an interactive
// login so the machine's owner is unambiguous.
// 路由: g.POST("/api/runners/bind-codes", h.issueRunnerBindCode)
func (h *runnersHandlers) issueRunnerBindCode(c *gin.Context) {
user, ok := h.requestUser(c.Request, true)
if !ok {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "请先登录后生成接入命令"})
return
}
raw := make([]byte, 16)
if _, err := rand.Read(raw); err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": "生成绑定码失败"})
return
}
code := runnerBindCodePrefix + base64.RawURLEncoding.EncodeToString(raw)
now := time.Now().UTC()
h.runnerBindMu.Lock()
// Opportunistically drop expired codes so the map cannot grow unbounded.
for key, entry := range h.runnerBindCodes {
if !entry.expiresAt.After(now) {
delete(h.runnerBindCodes, key)
}
}
h.runnerBindCodes[code] = runnerBindCode{userID: user.ID, expiresAt: now.Add(runnerBindCodeTTL)}
h.runnerBindMu.Unlock()
c.JSON(http.StatusOK, map[string]any{"code": code, "expiresAt": now.Add(runnerBindCodeTTL)})
}
// ---------- registration ----------
// resolveRunnerRegistrant accepts, in order: a one-time bind code from the
// 执行器 page (binds the machine to that user), the shared server bootstrap
// token, or a user personal token (afp_).
func (h *runnersHandlers) resolveRunnerRegistrant(r *http.Request) (ownerUserID int64, ok bool) {
provided := strings.TrimSpace(r.Header.Get("X-Bootstrap-Token"))
if provided == "" {
if raw, bearerOK := bearerToken(r); bearerOK {
provided = raw
}
}
if provided == "" {
return 0, false
}
if userID, matched := h.consumeRunnerBindCode(provided); matched {
return userID, true
}
if bootstrap := runnerBootstrapToken(); bootstrap != "" && constantTimeEqual(provided, bootstrap) {
return 0, true
}
if user, userOK := h.requestUser(r, true); userOK {
return user.ID, true
}
return 0, false
}
// runnerDeregister permanently removes an uninstalled machine. Ordinary
// daemon shutdown uses runnerDisconnect so service restarts retain identity.
// 路由: g.POST("/api/runners/deregister", h.runnerDeregister)
//
// g.POST("/runners/deregister", h.runnerDeregister)
func (h *runnersHandlers) runnerDeregister(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
if err := h.repo.DeregisterRunner(runner.ID, time.Now().UTC()); err != nil {
if err == repo.ErrRunnerNotFound {
c.JSON(http.StatusOK, map[string]bool{"ok": true})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// 路由: g.POST("/api/runners/register", h.runnerRegister)
//
// g.POST("/runners/register", h.runnerRegister)
func (h *runnersHandlers) runnerRegister(c *gin.Context) {
provided := strings.TrimSpace(c.GetHeader("X-Bootstrap-Token"))
if provided == "" {
if raw, bearerOK := bearerToken(c.Request); bearerOK {
provided = raw
}
}
owner, authorized := h.resolveRunnerRegistrant(c.Request)
if !authorized {
// No credential at all and no shared bootstrap token configured:
// registration is closed. A presented-but-invalid credential (for
// example an expired or replayed bind code) is always 401 so the
// machine-side message tells the user what to do next.
if provided == "" && runnerBootstrapToken() == "" {
c.JSON(http.StatusServiceUnavailable, map[string]string{"error": "runner registration is disabled: set AGENTFLOW_RUNNER_BOOTSTRAP_TOKEN on the server"})
return
}
c.Header("WWW-Authenticate", `Bearer realm="AgentFlow Runner"`)
if strings.HasPrefix(provided, runnerBindCodePrefix) {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "绑定码无效、已使用或已过期:请在「个人 → 执行器」页面刷新后重新复制命令"})
return
}
c.JSON(http.StatusUnauthorized, map[string]string{"error": "invalid bind token"})
return
}
var input struct {
RunnerID string `json:"runnerId"`
Name string `json:"name"`
OS string `json:"os"`
Arch string `json:"arch"`
Version string `json:"version"`
Labels []string `json:"labels"`
MaxConcurrency int `json:"maxConcurrency"`
Runtimes []domain.RunnerRuntime `json:"runtimes"`
}
if !decode(c, &input) {
return
}
if input.MaxConcurrency < 1 {
input.MaxConcurrency = 1
}
if input.MaxConcurrency > 32 {
input.MaxConcurrency = 32
}
// A re-registration with a known runner id rotates the session token and
// re-binds ownership to the token used for this registration.
now := time.Now().UTC()
runner := domain.Runner{
Name: strings.TrimSpace(input.Name),
OS: strings.TrimSpace(input.OS),
Arch: strings.TrimSpace(input.Arch),
RunnerVersion: strings.TrimSpace(input.Version),
Labels: input.Labels,
MaxConcurrency: input.MaxConcurrency,
Status: domain.RunnerStatusOnline,
Runtimes: normalizeRunnerRuntimes(input.Runtimes, nil),
OwnerUserID: owner,
LastSeenAt: &now,
}
if existing, ok := h.repo.Runner(strings.TrimSpace(input.RunnerID)); ok {
runner.ID = existing.ID
runner.CreatedAt = existing.CreatedAt
runner.Runtimes = normalizeRunnerRuntimes(input.Runtimes, existing.Runtimes)
} else {
runner.ID = "runner-" + randomID()
}
plain, hash, err := newRunnerSessionToken()
if err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": "生成 session token 失败"})
return
}
expires := now.Add(runnerSessionTTL)
runner.SessionTokenHash = hash
runner.SessionExpiresAt = &expires
if err := h.repo.PutRunner(runner); err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]any{
"runnerId": runner.ID,
"sessionToken": plain,
"expiresAt": expires,
"heartbeatInterval": 30 * time.Second,
"leaseTTL": runnerTaskLeaseTTL,
})
}
func normalizeRunnerRuntimes(reported, existing []domain.RunnerRuntime) []domain.RunnerRuntime {
preferences := map[string]domain.RunnerRuntime{}
for _, rt := range existing {
preferences[strings.ToLower(strings.TrimSpace(rt.Provider))] = rt
}
out := append([]domain.RunnerRuntime(nil), reported...)
for i := range out {
previous := preferences[strings.ToLower(strings.TrimSpace(out[i].Provider))]
if previous.Status == domain.RuntimeStatusDisabled {
out[i].Status = domain.RuntimeStatusDisabled
}
if domain.IsAgentCLIKind(out[i].Provider) && !domain.SupportsRunnerLogin(out[i].Provider) {
out[i].AuthMode = domain.RuntimeAuthPersonal
} else if previous.AuthMode == domain.RuntimeAuthLocal || previous.AuthMode == domain.RuntimeAuthPersonal {
out[i].AuthMode = previous.AuthMode
} else if strings.EqualFold(out[i].Provider, "codebuddy") {
out[i].AuthMode = domain.RuntimeAuthPersonal
} else {
out[i].AuthMode = domain.RuntimeAuthLocal
}
}
return out
}
// ---------- heartbeat ----------
// 路由: g.POST("/api/runners/heartbeat", h.runnerHeartbeat)
//
// g.POST("/runners/heartbeat", h.runnerHeartbeat)
func (h *runnersHandlers) runnerHeartbeat(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
var input struct {
Status string `json:"status"`
RunningTasks int `json:"runningTasks"`
Version string `json:"version"`
Runtimes []domain.RunnerRuntime `json:"runtimes"`
}
if !decode(c, &input) {
return
}
now := time.Now().UTC()
expires := now.Add(runnerSessionTTL)
if err := h.repo.RunnerHeartbeat(runner.ID, input.Runtimes, strings.TrimSpace(input.Version), now, expires); err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]any{"ok": true, "serverTime": now, "expiresAt": expires})
}
// ---------- task collection (management) ----------
// 路由: g.GET("/api/runners/tasks", h.runnerTasksCollection)
//
// g.POST("/api/runners/tasks", h.runnerTasksCollection)
func (h *runnersHandlers) runnerTasksCollection(c *gin.Context) {
if !h.requireRunnerTaskAdmin(c) {
return
}
switch c.Request.Method {
case http.MethodGet:
tasks := h.repo.RunnerTasks()
for i := range tasks {
tasks[i] = domain.PublicRunnerTask(tasks[i])
if len(tasks[i].Prompt) > 512 {
tasks[i].Prompt = tasks[i].Prompt[:512] + "..."
}
}
c.JSON(http.StatusOK, tasks)
case http.MethodPost:
var input struct {
Provider string `json:"provider"`
Prompt string `json:"prompt"`
Workspace string `json:"workspace"`
RunnerID string `json:"runnerId"`
Args []string `json:"args"`
MaxAttempts int `json:"maxAttempts"`
}
if !decode(c, &input) {
return
}
input.Provider = strings.TrimSpace(input.Provider)
if input.Provider == "" {
c.JSON(http.StatusBadRequest, map[string]string{"error": "provider 不能为空"})
return
}
if strings.TrimSpace(input.Prompt) == "" {
c.JSON(http.StatusBadRequest, map[string]string{"error": "prompt 不能为空"})
return
}
if input.MaxAttempts < 1 {
input.MaxAttempts = 1
}
if input.MaxAttempts > 5 {
input.MaxAttempts = 5
}
task := domain.RunnerTask{
ID: "rt-" + randomID(),
RunnerID: strings.TrimSpace(input.RunnerID),
Provider: input.Provider,
Prompt: input.Prompt,
Workspace: strings.TrimSpace(input.Workspace),
Args: input.Args,
Status: domain.RunnerTaskQueued,
MaxAttempts: input.MaxAttempts,
}
if err := h.repo.PutRunnerTask(task); err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
// Re-read so the response carries the persisted timestamps.
created, ok := h.repo.RunnerTask(task.ID)
if !ok {
created = task
}
// Wake any long-polling runner that can serve this provider.
h.runnerWaiters.notify([]string{task.Provider})
c.JSON(http.StatusCreated, created)
}
}
// ---------- long-poll claim ----------
func runnerLongPollTimeout() time.Duration {
if raw := strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_LONG_POLL_TIMEOUT")); raw != "" {
if parsed, err := time.ParseDuration(raw); err == nil && parsed > 0 && parsed <= 5*time.Minute {
return parsed
}
}
return runnerLongPollDefault
}
func runnerDBPollInterval() time.Duration {
if raw := strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_DB_POLL_INTERVAL")); raw != "" {
if parsed, err := time.ParseDuration(raw); err == nil && parsed > 0 && parsed <= 30*time.Second {
return parsed
}
}
return runnerDBPollDefault
}
// 路由: g.POST("/api/runners/tasks/claim", h.runnerTaskClaim)
//
// g.POST("/runners/tasks/claim", h.runnerTaskClaim)
func (h *runnersHandlers) runnerTaskClaim(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
var input struct {
AvailableRuntimes []string `json:"availableRuntimes"`
Capacity int `json:"capacity"`
Preflight bool `json:"preflight"`
NoWait bool `json:"noWait"`
}
if !decode(c, &input) {
return
}
if len(input.AvailableRuntimes) == 0 {
c.JSON(http.StatusBadRequest, map[string]string{"error": "availableRuntimes 不能为空"})
return
}
if input.Capacity <= 0 {
input.Capacity = 1
}
claimOrSignal := func() (domain.RunnerTask, bool, error) {
if input.Preflight {
available, err := h.repo.RunnerTaskAvailable(runner.ID, input.AvailableRuntimes)
return domain.RunnerTask{}, available, err
}
return h.repo.ClaimRunnerTask(runner.ID, input.AvailableRuntimes, time.Now().UTC(), runnerTaskLeaseTTL)
}
respond := func(task domain.RunnerTask) {
if input.Preflight {
c.JSON(http.StatusOK, map[string]bool{"taskAvailable": true})
return
}
if task.Invocation != nil && task.Invocation.GitSSHUserID > 0 && runner.SupportsGitSSH() && len(task.Invocation.GitSSHRemotes()) > 0 {
task.Invocation.GitSSHKeys = h.repo.GitSSHKeysForRemotes(task.Invocation.GitSSHUserID, task.Invocation.GitSSHRemotes())
task.Invocation.GitSSHUserID = 0
c.Header("Cache-Control", "no-store")
}
if task.Invocation != nil && task.Invocation.GitHTTPUserID > 0 && runner.SupportsGitHTTP() {
task.Invocation.GitHTTPCredentials = h.repo.GitHTTPCredentialSecrets(c.Request.Context(), task.Invocation.GitHTTPUserID)
task.Invocation.GitHTTPUserID = 0
c.Header("Cache-Control", "no-store")
}
c.JSON(http.StatusOK, map[string]any{"task": resolveRunnerTaskSandbox(task, runner.OS)})
}
deadline := time.Now().Add(runnerLongPollTimeout())
for {
if input.Capacity <= 0 {
c.JSON(http.StatusNoContent, nil)
return
}
task, claimed, err := claimOrSignal()
if err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
if claimed {
respond(task)
return
}
if input.NoWait {
c.Status(http.StatusNoContent)
return
}
remaining := time.Until(deadline)
if remaining <= 0 {
c.Status(http.StatusNoContent)
return
}
// Register before the second claim. This closes the race where a task
// is inserted after the first DB check but before the waiter exists.
// In an all-in-one process the waiter is notified immediately. In the
// production API/worker split, the worker writes the durable queue from
// another process, so a bounded DB poll is also required.
waiter := h.runnerWaiters.register(input.AvailableRuntimes)
task, claimed, err = claimOrSignal()
if err != nil {
h.runnerWaiters.unregister(waiter)
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
if claimed {
h.runnerWaiters.unregister(waiter)
respond(task)
return
}
waitFor := runnerDBPollInterval()
if remaining < waitFor {
waitFor = remaining
}
wake := time.NewTimer(waitFor)
select {
case <-waiter.ch:
case <-wake.C:
case <-c.Request.Context().Done():
h.runnerWaiters.unregister(waiter)
wake.Stop()
return
}
wake.Stop()
h.runnerWaiters.unregister(waiter)
}
}
// ---------- task item endpoints (session-authenticated) ----------
//
// 原 runnerTaskItem 分发器按 "{id}" / "{id}/{action}" 拆分为独立 handler,
// id 由 gin 路由参数 :id 提供。
// runnerTaskGet returns one task by id.
// 路由: g.GET("/api/runners/tasks/:id", h.runnerTaskGet)
func (h *runnersHandlers) runnerTaskGet(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
task, exists := h.repo.RunnerTask(c.Param("id"))
if !exists || !runnerMaySeeTask(runner, task) {
c.Status(http.StatusNotFound)
return
}
c.JSON(http.StatusOK, domain.PublicRunnerTask(resolveRunnerTaskSandbox(task, runner.OS)))
}
// resolveRunnerTaskSandbox hands the runner a concrete sandbox driver: the
// native option becomes seatbelt or bwrap by the OS the runner reported, so
// runner builds that predate native keep working. A runner on an
// unsupported OS keeps native and reports the error when it opens the
// sandbox.
func resolveRunnerTaskSandbox(task domain.RunnerTask, runnerOS string) domain.RunnerTask {
if task.Sandbox == nil {
return task
}
driver, err := domain.ResolveSandboxDriver(task.Sandbox.Profile.Driver, runnerOS)
if err != nil || driver == task.Sandbox.Profile.Driver {
return task
}
spec := *task.Sandbox
spec.Profile.Driver = driver
task.Sandbox = &spec
return task
}
// runnerMaySeeTask limits task reads to the runner it is targeted at or
// leased by. An untargeted, unleased task is visible to every runner because
// any of them may claim it.
func runnerMaySeeTask(runner domain.Runner, task domain.RunnerTask) bool {
if task.LeaseOwner != "" {
return task.LeaseOwner == runner.ID
}
return task.RunnerID == "" || task.RunnerID == runner.ID
}
// requireRunnerTaskAdmin guards raw task management (list/create/cancel):
// creating a task runs an arbitrary prompt on a user's machine, and the list
// exposes every project's prompts. Only platform admins may use it once
// authentication is enabled; the engine dispatches workflow tasks directly.
func (h *runnersHandlers) requireRunnerTaskAdmin(c *gin.Context) bool {
if !authRequired() || h.isPlatformAdmin(c.Request) {
return true
}
c.JSON(http.StatusForbidden, map[string]string{"error": "只有平台管理员可以直接管理执行机器任务"})
return false
}
// runnerTaskCancel is a management action: it authenticates the interactive
// user (userAccessAuth), not the runner session.
// 路由: g.POST("/api/runners/tasks/:id/cancel", h.runnerTaskCancel)
func (h *runnersHandlers) runnerTaskCancel(c *gin.Context) {
if !h.requireRunnerTaskAdmin(c) {
return
}
taskID := c.Param("id")
if err := h.repo.CancelRunnerTask(taskID, time.Now().UTC()); err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
h.engine.NotifyRunnerTaskChanged(taskID)
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// runnerTaskEventsOut serves stored task events to management callers.
// 路由: g.GET("/api/runners/tasks/:id/events", h.runnerTaskEventsOut)
func (h *runnersHandlers) runnerTaskEventsOut(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
task, exists := h.repo.RunnerTask(c.Param("id"))
if !exists || !runnerMaySeeTask(runner, task) {
c.Status(http.StatusNotFound)
return
}
c.JSON(http.StatusOK, h.repo.RunnerTaskEvents(task.ID))
}
// runnerTaskStart acknowledges the runner picked up the leased task.
// 路由: g.POST("/api/runners/tasks/:id/start", h.runnerTaskStart)
//
// g.POST("/runners/tasks/:id/start", h.runnerTaskStart)
func (h *runnersHandlers) runnerTaskStart(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
if err := h.repo.StartRunnerTask(c.Param("id"), runner.ID, time.Now().UTC()); err != nil {
if err == repo.ErrRunnerTaskLeaseLost {
c.JSON(http.StatusConflict, map[string]string{"error": "task lease lost"})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// runnerTaskLeaseRenew extends the lease and reports the desired state.
// 路由: g.POST("/api/runners/tasks/:id/lease/renew", h.runnerTaskLeaseRenew)
//
// g.POST("/runners/tasks/:id/lease/renew", h.runnerTaskLeaseRenew)
func (h *runnersHandlers) runnerTaskLeaseRenew(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
desired, err := h.repo.RenewRunnerTaskLease(c.Param("id"), runner.ID, runnerTaskLeaseTTL, time.Now().UTC())
if err != nil {
if err == repo.ErrRunnerTaskLeaseLost {
c.JSON(http.StatusConflict, map[string]string{"error": "task lease lost"})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]any{"leaseUntil": time.Now().UTC().Add(runnerTaskLeaseTTL), "desiredState": desired})
}
// runnerTaskEventsIngest accepts batched task events from the lease owner.
// 路由: g.POST("/api/runners/tasks/:id/events", h.runnerTaskEventsIngest)
//
// g.POST("/runners/tasks/:id/events", h.runnerTaskEventsIngest)
func (h *runnersHandlers) runnerTaskEventsIngest(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
taskID := c.Param("id")
task, exists := h.repo.RunnerTask(taskID)
if !exists {
c.Status(http.StatusNotFound)
return
}
// Events are accepted from the lease owner; retries after a lease loss
// are idempotent through (task_id, seq) anyway.
if task.LeaseOwner != runner.ID || (task.Status != domain.RunnerTaskLeased && task.Status != domain.RunnerTaskRunning) {
c.JSON(http.StatusConflict, map[string]string{"error": "task lease lost"})
return
}
var input struct {
Events []domain.RunnerTaskEvent `json:"events"`
}
if !decode(c, &input) {
return
}
if len(input.Events) == 0 {
c.JSON(http.StatusOK, map[string]int{"accepted": 0})
return
}
if len(input.Events) > 500 {
c.JSON(http.StatusBadRequest, map[string]string{"error": "单批事件数量不能超过 500"})
return
}
for i := range input.Events {
if input.Events[i].Type == "" {
input.Events[i].Type = "stdout"
}
if input.Events[i].Ts.IsZero() {
input.Events[i].Ts = time.Now().UTC()
}
}
accepted, err := h.repo.AppendRunnerTaskEvents(taskID, input.Events)
if err != nil {
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]int{"accepted": accepted})
}
// runnerTaskComplete closes out a task with result and artifacts.
// 路由: g.POST("/api/runners/tasks/:id/complete", h.runnerTaskComplete)
//
// g.POST("/runners/tasks/:id/complete", h.runnerTaskComplete)
func (h *runnersHandlers) runnerTaskComplete(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
var input struct {
Status string `json:"status"`
ExitCode *int `json:"exitCode"`
Result string `json:"result"`
Error string `json:"error"`
Artifacts map[string]string `json:"artifacts"`
Outputs *domain.RunnerTaskOutputs `json:"outputs"`
}
if !decode(c, &input) {
return
}
if input.Status == "" {
input.Status = domain.RunnerTaskSuccess
}
if len(input.Artifacts) > 64 {
c.JSON(http.StatusBadRequest, map[string]string{"error": "单次最多上报 64 个产物文件"})
return
}
for name, content := range input.Artifacts {
if len(content) > 1<<20 {
c.JSON(http.StatusBadRequest, map[string]string{"error": fmt.Sprintf("产物 %s 超过 1MB 上传限制", name)})
return
}
}
if message := validateRunnerTaskOutputs(input.Outputs); message != "" {
c.JSON(http.StatusBadRequest, map[string]string{"error": message})
return
}
if err := h.repo.CompleteRunnerTask(c.Param("id"), runner.ID, input.Status, input.ExitCode, input.Result, input.Error, input.Artifacts, input.Outputs, time.Now().UTC()); err != nil {
if err == repo.ErrRunnerTaskLeaseLost {
c.JSON(http.StatusConflict, map[string]string{"error": "task lease lost"})
return
}
c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
return
}
h.engine.NotifyRunnerTaskChanged(c.Param("id"))
if task, ok := h.repo.RunnerTask(c.Param("id")); ok {
h.engine.OnRunnerTaskCompleted(task)
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
// runnerTaskControl lets the runner poll the desired state while running.
// 路由: g.GET("/api/runners/tasks/:id/control", h.runnerTaskControl)
//
// g.GET("/runners/tasks/:id/control", h.runnerTaskControl)
func (h *runnersHandlers) runnerTaskControl(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
task, exists := h.repo.RunnerTaskControl(c.Param("id"))
if !exists {
c.Status(http.StatusNotFound)
return
}
if task.LeaseOwner != runner.ID {
c.JSON(http.StatusConflict, map[string]string{"error": "task lease lost"})
return
}
c.JSON(http.StatusOK, map[string]any{
"desiredState": task.DesiredState,
"status": task.Status,
"leaseOwner": task.LeaseOwner,
})
}
// isRunnerAgentPath reports whether a path is a runner-agent endpoint that
// authenticates with bootstrap/session credentials instead of a user session.
// Used by userAccessAuth to skip the user-identity requirement. Method checks
// and session validation happen inside each handler, so an exempted path never
// exposes data without its own credential.
// validateRunnerTaskOutputs applies the per-file limits of legacy artifact
// uploads to reported outputs and rejects paths outside the task workspace.
func validateRunnerTaskOutputs(outputs *domain.RunnerTaskOutputs) string {
if outputs == nil {
return ""
}
if len(outputs.Files) > 64 {
return "单次最多上报 64 个产物文件"
}
if len(outputs.Patches) > 64 {
return "单次最多上报 64 个仓库的变更清单"
}
for path, content := range outputs.Files {
if !domain.SafeWorkspaceRelPath(path) {
return fmt.Sprintf("产物路径 %q 不合法", path)
}
if len(content) > 1<<20 {
return fmt.Sprintf("产物 %s 超过 1MB 上传限制", path)
}
}
for dir, patch := range outputs.Patches {
if dir != "" && !domain.SafeWorkspaceRelPath(dir) {
return fmt.Sprintf("仓库目录 %q 不合法", dir)
}
if len(patch) > 1<<20 {
return fmt.Sprintf("仓库 %s 的变更清单超过 1MB", dir)
}
}
if len(outputs.Recovered) > 64 {
return "单次最多上报 64 条收回记录"
}
return ""
}
func isRunnerAgentPath(path string) bool {
if strings.HasPrefix(path, "/runners/") {
return true
}
if !strings.HasPrefix(path, "/api/runners/") {
return false
}
rest := strings.Trim(strings.TrimPrefix(path, "/api/runners/"), "/")
switch rest {
case "register", "deregister", "disconnect", "heartbeat", "tasks/claim":
return true
}
// tasks/{id} and tasks/{id}/{action}: only the runner-agent actions are
// exempt; task creation (POST /api/runners/tasks) and cancel stay behind
// user auth.
if after, ok := strings.CutPrefix(rest, "tasks/"); ok && after != "" {
parts := strings.Split(after, "/")
if len(parts) == 1 {
return true
}
switch strings.Join(parts[1:], "/") {
case "start", "lease/renew", "events", "complete", "control":
return true
}
}
return false
}
// runnerPreviewContent accepts a runner's compressed preview upload. The
// upload token comes from the task payload; the runner session identifies the
// uploader.
func (h *runnersHandlers) runnerPreviewContent(c *gin.Context) {
runner, ok := h.runnerSessionAuth(c)
if !ok {
return
}
svc := h.engine.Preview()
if svc == nil {
c.JSON(http.StatusNotFound, map[string]string{"error": "preview is not enabled"})
return
}
token := strings.TrimSpace(c.GetHeader("X-Preview-Upload-Token"))
if token == "" {
c.JSON(http.StatusUnauthorized, map[string]string{"error": "preview upload token required"})
return
}
c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, svc.Config().MaxCompressed+1)
if err := svc.AcceptUpload(c.Request.Context(), c.Param("previewId"), runner.ID, token, c.Request.Body); err != nil {
c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
return
}
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}
func (h *runnersHandlers) runnerPreviewComplete(c *gin.Context) {
if _, ok := h.runnerSessionAuth(c); !ok {
return
}
_, _ = io.Copy(io.Discard, io.LimitReader(c.Request.Body, 1<<20))
c.JSON(http.StatusOK, map[string]bool{"ok": true})
}