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 engine
import (
"context"
"errors"
"fmt"
"os"
"strings"
"sync"
"sync/atomic"
"agentflow/internal/domain"
"agentflow/internal/repo"
"agentflow/internal/runtime"
)
// runEnvironment owns the single sandbox/workspace assigned to a workflow run.
// SOP nodes and group tasks hold nodeMu only while preparing the shared
// environment (checkout, preparation scripts, inputs); parallel branches then
// execute concurrently and are counted in activeExecutions.
type runEnvironment struct {
sandbox runtime.Sandbox
nodeMu sync.Mutex
credentials runtime.RunCredentials
credentialsMu sync.RWMutex
repositoriesPrepared bool
preparing atomic.Bool
activeExecutions atomic.Int64
outputsMu sync.Mutex
// reported holds, per node, what the execution machine reports when it
// supports RunnerTask.Outputs; absent nodes use the sandbox workspace.
reported map[string]*reportedOutputs
}
func (r *runEnvironment) beginReportedOutputs(nodeID string, inputs []domain.RunnerInputFile) *reportedOutputs {
r.outputsMu.Lock()
defer r.outputsMu.Unlock()
if r.reported == nil {
r.reported = map[string]*reportedOutputs{}
}
outputs := newReportedOutputs(inputs)
r.reported[nodeID] = outputs
return outputs
}
func (r *runEnvironment) reportedOutputs(nodeID string) *reportedOutputs {
r.outputsMu.Lock()
defer r.outputsMu.Unlock()
return r.reported[nodeID]
}
func (r *runEnvironment) endReportedOutputs(nodeID string) {
r.outputsMu.Lock()
defer r.outputsMu.Unlock()
delete(r.reported, nodeID)
}
// prepareRepositoriesOnce keeps repository checkout at the run-environment
// lifecycle. nodeMu serializes callers, and a reconstructed environment starts
// with repositoriesPrepared=false so process restarts and lease takeovers
// still revalidate the persisted workspace once before executing a node.
func (r *runEnvironment) prepareRepositoriesOnce(prepare func() error) error {
if r.repositoriesPrepared {
return nil
}
if err := prepare(); err != nil {
return err
}
r.repositoriesPrepared = true
return nil
}
func (r *runEnvironment) ID() string { return r.sandbox.ID() }
func (r *runEnvironment) Workspace() string { return r.sandbox.Workspace() }
func (r *runEnvironment) Unwrap() runtime.Sandbox {
if r == nil {
return nil
}
return r.sandbox
}
func (r *runEnvironment) Driver() string {
if value, ok := r.sandbox.(interface{ Driver() string }); ok {
return value.Driver()
}
return ""
}
func (r *runEnvironment) Exec(ctx context.Context, command runtime.CommandSpec, sink runtime.EventSink) (string, error) {
return r.sandbox.Exec(ctx, command, sink)
}
func (r *runEnvironment) Recreate(ctx context.Context) error {
if rec, ok := r.sandbox.(interface{ Recreate(context.Context) error }); ok {
return rec.Recreate(ctx)
}
return nil
}
func (r *runEnvironment) BindWorkspace(ctx context.Context) error {
if bind, ok := r.sandbox.(interface{ BindWorkspace(context.Context) error }); ok {
return bind.BindWorkspace(ctx)
}
return r.Recreate(ctx)
}
func (r *runEnvironment) Close(ctx context.Context) error { return r.sandbox.Close(ctx) }
func (r *runEnvironment) Detach() error {
if detach, ok := r.sandbox.(interface{ Detach() error }); ok {
return detach.Detach()
}
return nil
}
func resolveSandboxResources(st *repo.Store, profile domain.SandboxProfile) (runtime.SandboxResources, error) {
var resources runtime.SandboxResources
if strings.TrimSpace(profile.DockerfileID) != "" {
dockerfile, ok := st.Dockerfile(profile.DockerfileID)
if !ok {
return resources, fmt.Errorf("dockerfile %q not found", profile.DockerfileID)
}
resources.Dockerfile = dockerfile
} else if strings.EqualFold(strings.TrimSpace(profile.Driver), "docker") {
return resources, fmt.Errorf("docker sandbox %q requires a dockerfileId", profile.ID)
}
if strings.TrimSpace(profile.EnvironmentID) != "" {
if environment, ok := st.Environment(profile.EnvironmentID); ok {
resources.Environment = environment
}
}
return resources, nil
}
func resolvedSandboxSnapshot(profile domain.SandboxProfile, resources runtime.SandboxResources) *domain.RunnerSandboxSpec {
snapshot := &domain.RunnerSandboxSpec{Profile: profile}
if strings.TrimSpace(resources.Dockerfile.ID) != "" {
dockerfile := resources.Dockerfile
snapshot.Dockerfile = &dockerfile
}
if strings.TrimSpace(resources.Environment.ID) != "" {
environment := resources.Environment
snapshot.Environment = &environment
}
return snapshot
}
func sandboxResourcesFromSnapshot(snapshot *domain.RunnerSandboxSpec) runtime.SandboxResources {
var resources runtime.SandboxResources
if snapshot == nil {
return resources
}
if snapshot.Dockerfile != nil {
resources.Dockerfile = *snapshot.Dockerfile
}
if snapshot.Environment != nil {
resources.Environment = *snapshot.Environment
}
return resources
}
func (e *Engine) acquireRunEnvironment(ctx context.Context, run domain.Run, profile domain.SandboxProfile, requirements runtime.SandboxRequirements, onWorkspaceBusy ...func()) (*runEnvironment, bool, error) {
needsRestore := !run.WorkspaceCleanedAt.IsZero()
if !needsRestore && !sharesWorkspace(run) && e.defaultExecutionRunner(run) == "" {
if _, saved := e.repo.WorkspaceCheckpoint(run.ID); saved {
_, err := os.Stat(e.sandboxes.RunWorkspace(run.ID))
needsRestore = os.IsNotExist(err)
}
}
if needsRestore {
var onBusy func()
if len(onWorkspaceBusy) > 0 {
onBusy = onWorkspaceBusy[0]
}
if err := e.restoreCheckpointForExecution(ctx, run, onBusy); err != nil {
return nil, false, err
}
}
current, ok := e.repo.RunState(run.ID)
if !ok || current.Generation != run.Generation || !e.ownsRun(current) {
return nil, false, repo.ErrRunLeaseLost
}
if err := e.adoptForeignWorkspace(current); err != nil {
return nil, false, err
}
e.runEnvMu.Lock()
defer e.runEnvMu.Unlock()
// Credentials are resolved from the responsible user on every entry. The
// sandbox directory stays; only the in-memory handle is refreshed. A retry
// otherwise keeps the token captured at the first acquire, including an
// empty token from a run that had no responsible user yet.
credentials := e.resolveRunCredentials(current)
if existing := e.runEnvs[run.ID]; existing != nil {
existing.setCredentials(credentials)
return existing, false, nil
}
resources := sandboxResourcesFromSnapshot(run.WorkflowSnapshot.SandboxSnapshot)
if run.WorkflowSnapshot.SandboxSnapshot == nil {
var err error
resources, err = resolveSandboxResources(e.repo, profile)
if err != nil {
return nil, false, err
}
}
sandbox, err := e.sandboxes.AcquireRunIn(ctx, run.ID, workspaceRunID(current), profile, requirements, credentials, resources)
if err != nil {
return nil, false, err
}
env := &runEnvironment{
sandbox: sandbox,
credentials: credentials,
}
e.runEnvs[run.ID] = env
first, err := e.repo.BindRunWorkspace(run.ID, e.instanceID, run.Generation, e.workspaceHost, e.sandboxes.Root())
if err == nil && !current.WorkspaceCleanedAt.IsZero() {
// Legacy runs without an archive are rebuilt by normal execution, not
// restored by the preflight. Once a real sandbox exists, clear the old
// cleanup marker so follow-up writes and checkpoint capture can use it.
err = e.repo.ResetRunWorkspaceCleanup(run.ID)
}
if err != nil {
delete(e.runEnvs, run.ID)
_ = env.Close(context.Background())
return nil, false, err
}
return env, first, nil
}
func (e *Engine) resolveRunCredentials(run domain.Run) runtime.RunCredentials {
userID := run.ExecutionContext.ResponsibleUserID
credentials := runtime.RunCredentials{
CodeBuddy: resolveCodeBuddyCredential(e.repo, userID),
GitHTTPCredentials: e.repo.GitHTTPCredentialSecrets(context.Background(), userID),
}
credentials.Extra = runtime.ExtraRunCredentials(userID)
credentials.GitSSHKeys = e.repo.GitSSHKeysForRemotes(userID, sshRepositoryURLs(run.RepositoryContexts()))
identity := resolveGitIdentity(e.repo, userID)
credentials.GitUserName = identity.name
credentials.GitUserEmail = identity.email
if user, ok := e.repo.User(userID); ok {
credentials.Codex = runtime.ProviderCredential{APIKey: user.CodexAPIKey, BaseURL: user.CodexBaseURL}
credentials.ClaudeCode = runtime.ProviderCredential{APIKey: user.ClaudeCodeAPIKey, BaseURL: user.ClaudeCodeBaseURL}
credentials.AgentCLI = runtime.AgentCLIUserCredentials(user)
}
scriptAssets, _, _ := runtime.PrepareMCPServers(e.resolveScriptMCPAssets(run.ExecutionContext.ProjectID, userID), runtime.MCPTarget{
GitHTTPCredentials: credentials.GitHTTPCredentials,
ExtraCredentials: credentials.Extra,
})
credentials.MCPServers = scriptAssets.MCPServers
return credentials
}
func (env *runEnvironment) credentialSnapshot() runtime.RunCredentials {
env.credentialsMu.RLock()
defer env.credentialsMu.RUnlock()
return env.credentials
}
func (env *runEnvironment) setCredentials(credentials runtime.RunCredentials) {
env.credentialsMu.Lock()
env.credentials = credentials
env.credentialsMu.Unlock()
if sink, ok := env.sandbox.(interface {
SetCredentials(runtime.RunCredentials)
}); ok {
sink.SetCredentials(credentials)
}
}
// adoptForeignWorkspace handles a run whose bound host is gone. A workspace
// without code changes is simply moved to this instance. One that held code
// changes lost them with the host: the bind is still moved so a rerun starts
// from a fresh checkout here, but the current attempt fails instead of
// silently continuing without the earlier nodes' work.
func (e *Engine) adoptForeignWorkspace(run domain.Run) error {
if !e.foreignWorkspaceBind(run) {
return nil
}
if e.workspaceBlocked(run) {
return repo.ErrRunWorkspaceBound
}
lost := hasCodeWorkspace(run)
message := e.workspaceLostMessage(run)
if sharesWorkspace(run) {
// The checkout belongs to the parent; only its rerun may rebuild it.
return errors.New(message)
}
if err := e.rebindWorkspaceHere(run, lost); err != nil {
return err
}
if lost {
return errors.New(message)
}
return nil
}
// rebindWorkspaceHere moves a run's workspace bind from a host that is gone
// to this instance. Whatever this host still has under the run ID is a
// leftover of an earlier stay and is discarded, so the next node starts from
// a fresh checkout.
func (e *Engine) rebindWorkspaceHere(run domain.Run, lost bool) error {
if err := e.releaseRunEnvironment(run.ID, true); err != nil {
return fmt.Errorf("discard stale local workspace: %w", err)
}
if err := e.repo.RebindRunWorkspace(run.ID, e.instanceID, run.Generation, e.workspaceHost, e.sandboxes.Root()); err != nil {
return err
}
message := fmt.Sprintf("工作区原绑定 %s:%s 已离线,改由 %s 重新拉取代码", run.WorkspaceHost, run.WorkspaceRoot, e.workspaceHost)
if lost {
message += ";之前节点的代码改动未推送到远端,已随原机器丢失"
}
e.updateRun(run.ID, func(r *domain.Run) {
r.WorkspaceHost, r.WorkspaceRoot = e.workspaceHost, e.sandboxes.Root()
e.event(r, "", "workspace.rebound", message)
})
return nil
}
func (e *Engine) releaseRunEnvironment(runID string, destroy bool) error {
e.runEnvMu.Lock()
env := e.runEnvs[runID]
delete(e.runEnvs, runID)
if destroy {
delete(e.workspaceFacts, runID)
}
e.runEnvMu.Unlock()
var closeErr error
if env != nil {
closeErr = env.Close(context.Background())
}
if destroy {
if err := e.sandboxes.DestroyRun(runID); err != nil {
if closeErr != nil {
return fmt.Errorf("close run sandbox: %v; destroy workspace: %w", closeErr, err)
}
return err
}
}
return closeErr
}
func (e *Engine) detachRunEnvironment(runID string) {
e.runEnvMu.Lock()
env := e.runEnvs[runID]
delete(e.runEnvs, runID)
e.runEnvMu.Unlock()
if env != nil {
_ = env.Detach()
}
}
func (e *Engine) detachAllRunEnvironments() {
e.runEnvMu.Lock()
ids := make([]string, 0, len(e.runEnvs))
for id := range e.runEnvs {
ids = append(ids, id)
}
e.runEnvMu.Unlock()
for _, id := range ids {
e.detachRunEnvironment(id)
}
}
// LocalRunWorkspace resolves a control-plane workspace only when this process
// can read the authoritative checkout. Runner-owned workspaces use the
// bounded read-only channel maintained by the HTTP layer.
func (e *Engine) LocalRunWorkspace(run domain.Run) (string, string) {
if e.defaultExecutionRunner(run) != "" {
return "", "工作区位于远程执行机器,当前版本暂不支持远程浏览"
}
if e.foreignWorkspaceBind(run) {
return "", "工作区绑定在其他 LoopForge 实例"
}
workspace := e.sandboxes.RunWorkspace(workspaceRunID(run))
if strings.TrimSpace(workspace) == "" {
return "", "当前实例未配置工作区目录"
}
return workspace, ""
}
// RunExecutionRunner returns the execution machine frozen into the run.
// Empty means that the authoritative workspace belongs to the control plane.
func (e *Engine) RunExecutionRunner(run domain.Run) string {
return e.defaultExecutionRunner(run)
}