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"
"encoding/json"
"fmt"
"strings"
"agentflow/internal/domain"
"agentflow/internal/procwatch"
"agentflow/internal/repo"
"agentflow/internal/runtime"
)
func (e *Engine) workspaceSandboxProfile(run domain.Run) (domain.SandboxProfile, runtime.SandboxResources, error) {
if spec := run.WorkflowSnapshot.SandboxSnapshot; spec != nil {
return spec.Profile, sandboxResourcesFromSnapshot(spec), nil
}
id := strings.TrimSpace(run.WorkflowSnapshot.SandboxProfileID)
if id == "" {
id = "local"
}
profile, ok := e.repo.Sandbox(id)
if !ok {
return profile, runtime.SandboxResources{}, fmt.Errorf("sandbox profile %q not found", id)
}
resources, err := resolveSandboxResources(e.repo, profile)
return profile, resources, err
}
// acquireConversationEnvironment does not acquire or steal the SOP scheduler
// lease. The workspace-use lease fences cleanup; the sandbox's workspace flock
// fences another process. An active local scheduler shares its existing handle.
func (e *Engine) acquireConversationEnvironment(ctx context.Context, run domain.Run) (*runEnvironment, error) {
if latest, ok := e.repo.RunState(run.ID); ok {
run = latest
}
if e.foreignWorkspaceBind(run) || e.defaultExecutionRunner(run) != "" {
return nil, fmt.Errorf("工作区属于其他执行实例")
}
if !run.WorkspaceCleanedAt.IsZero() {
if meta, saved := e.repo.WorkspaceCheckpoint(run.ID); saved && meta.SavedAt != nil {
return nil, fmt.Errorf("工作区已回收,请先恢复快照后再打开环境")
}
}
e.runEnvMu.Lock()
defer e.runEnvMu.Unlock()
if env := e.runEnvs[run.ID]; env != nil {
env.setCredentials(e.resolveRunCredentials(run))
return env, nil
}
profile, resources, err := e.workspaceSandboxProfile(run)
if err != nil {
return nil, err
}
requirements, err := workspaceConversationRequirements(e.repo, run.WorkflowSnapshot, false)
if err != nil {
return nil, err
}
credentials := e.resolveRunCredentials(run)
sb, err := e.sandboxes.AcquireRunIn(ctx, run.ID, workspaceRunID(run), profile, requirements, credentials, resources)
if err != nil {
return nil, err
}
env := &runEnvironment{sandbox: sb, credentials: credentials}
e.runEnvs[run.ID] = env
return env, nil
}
func (e *Engine) preparationSink(runID string) runtime.EventSink {
return func(event domain.TelemetryEvent) {
switch event.Name {
case "workspace.preparation.started", "workspace.preparation.completed", "workspace.preparation.failed":
e.AppendRunEvent(runID, event.Name, event.Message)
}
}
}
// withPreparationProgress records clone and image-build steps on the run while
// they happen. A conversation workspace has no nodes, so these events are the
// only place a slow or failed checkout or build shows up.
func (e *Engine) withPreparationProgress(ctx context.Context, runID string) context.Context {
return procwatch.WithObserver(ctx, func(event procwatch.Event) {
e.AppendRunEvent(runID, "workspace."+event.Stage+"."+string(event.Kind), event.Message)
})
}
func (e *Engine) prepareLocalEnvironment(ctx context.Context, run domain.Run, env *runEnvironment) (runtime.WorkspacePreparationStatus, error) {
// The first sandbox call below builds the Docker image when it is missing.
ctx = e.withPreparationProgress(ctx, run.ID)
env.preparing.Store(true)
defer env.preparing.Store(false)
// Caller owns env.nodeMu so reconstruction is serialized without turning
// environment preparation into business-node attempts.
assets := e.resolveScriptMCPAssets(run.ExecutionContext.ProjectID, run.ExecutionContext.ResponsibleUserID)
if len(runtime.PreparationNodes(workspacePreparationPlan(run))) > 0 {
if err := runtime.ProvisionMCPAssets(ctx, env, env.Workspace(), assets, nil); err != nil {
return runtime.WorkspacePreparationStatus{Status: "failed", Error: err.Error(), Steps: []runtime.WorkspacePreparationStep{}}, err
}
}
return runtime.EnsureWorkspacePreparation(ctx, env.sandbox, workspacePreparationPlan(run), run.RepositoryContexts(), e.preparationSink(run.ID))
}
func (e *Engine) preparedWorkspaceRequest(run domain.Run, request domain.RunnerWorkspaceRequest) (domain.RunnerWorkspaceRequest, error) {
runnerID := e.defaultExecutionRunner(run)
if runnerID != "" {
if run.ExecutionContext.RunnerWorkspaceLayout != domain.RunnerWorkspaceLayoutShared && len(runtime.PreparationNodes(runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot))) > 0 {
return request, fmt.Errorf("此历史运行使用逐节点工作区,不能自动重建共享环境;请重新发起一次运行")
}
runner, ok := e.repo.Runner(runnerID)
if run.IsWorkspace() && (!ok || !runner.SupportsConversationWorkspace()) {
return request, fmt.Errorf("对话工作区需要执行机器升级至 %s", domain.RunnerVersionConversationWorkspace)
}
if !ok || !runner.SupportsWorkspacePreparation() {
return request, fmt.Errorf("执行机器需升级至 %s 才能准备环境或打开沙箱终端", domain.RunnerVersionWorkspacePreparation)
}
if sharesWorkspace(run) && !runner.SupportsWorkspaceOwnerPreparation() {
return request, fmt.Errorf("执行机器需升级至 %s 才能操作共享父工作区中的子 SOP 环境", domain.RunnerVersionWorkspaceOwnerPreparation)
}
}
spec, err := e.runnerSandboxSpec(run)
if err != nil {
return request, err
}
request.RunID = run.ID
request.RunKind = run.Kind
request.WorkspaceRunID = workspaceRunID(run)
request.RefreshCleanRepositories = request.Operation == domain.RunnerWorkspaceOperationPrepare && workspaceCanRefreshRepositories(run)
request.Sandbox = spec
// Requests are constructed from the persisted frozen run, never client JSON.
wf := workspacePreparationPlan(run)
if request.Operation == domain.RunnerWorkspaceOperationPreparationRecord {
wf = runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot)
found := false
for _, node := range wf.Nodes {
if node.ID == request.PreparationNodeID && node.RunOnWorkspaceRebuild {
found = true
break
}
}
if !found {
return request, fmt.Errorf("节点未启用工作区重建执行")
}
}
request.Workflow = &wf
request.Repositories = run.RepositoryContexts()
credentials := e.resolveRunCredentials(run)
invocation := &domain.RunnerInvocation{}
bindRunnerRepositories(invocation, run, credentials.GitUserName, credentials.GitUserEmail)
invocation.GitSSHUserID = 0
invocation.GitHTTPUserID = 0
assets := e.resolveScriptMCPAssets(run.ExecutionContext.ProjectID, run.ExecutionContext.ResponsibleUserID)
invocation.Assets = assets
invocation.MCPCallServers = assets.MCPServers
request.PreparationInvocation = invocation
// Status and terminal I/O don't need keys. A separate platform instance
// can also resolve its own credentials from the shared store.
request.TerminalGitSSHKeys = nil
request.TerminalGitHTTPCredentials = nil
terminalOpen := request.Operation == domain.RunnerWorkspaceOperationTerminal && request.Terminal != nil && request.Terminal.Operation == "open"
if runnerID != "" && (request.Operation == domain.RunnerWorkspaceOperationPrepare || terminalOpen) {
invocation.GitHTTPCredentials = credentials.GitHTTPCredentials
if len(invocation.GitSSHRemotes()) > 0 {
invocation.GitSSHKeys = credentials.GitSSHKeys
}
}
if runnerID != "" && terminalOpen {
terminalCredentials := e.WorkspaceTerminalGitCredentials(context.Background(), run, request.TerminalOwner)
request.TerminalGitHTTPCredentials = terminalCredentials.HTTPS
request.TerminalGitSSHKeys = terminalCredentials.SSHKeys
}
request.RunStatus = run.Status
request.WorkspaceLayout = run.ExecutionContext.RunnerWorkspaceLayout
return request, nil
}
func workspaceCanRefreshRepositories(run domain.Run) bool {
if sharesWorkspace(run) {
return false
}
preparation := map[string]bool{}
for _, node := range runtime.PreparationNodes(runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot)) {
preparation[node.ID] = true
}
for id, node := range run.Nodes {
if node != nil && node.Attempt > 0 && !preparation[id] {
return false
}
}
return true
}
func (e *Engine) remoteWorkspacePreparation(ctx context.Context, run domain.Run, operation string) (runtime.WorkspacePreparationStatus, error) {
request, err := e.preparedWorkspaceRequest(run, domain.RunnerWorkspaceRequest{RunID: run.ID, Operation: operation})
if err != nil {
return runtime.WorkspacePreparationStatus{}, err
}
response, err := e.requestWorkspaceCheckpoint(ctx, run, request)
if err != nil {
return runtime.WorkspacePreparationStatus{}, err
}
var state runtime.WorkspacePreparationStatus
if len(response.Payload) > 0 {
_ = json.Unmarshal(response.Payload, &state)
}
if response.Error != "" {
if state.Status == "" {
state.Status = "failed"
}
state.Error = response.Error
return state, runnerWorkspaceResponseError(response)
}
if state.Status == "" {
return state, fmt.Errorf("执行端尚不支持工作区准备,请更新执行器")
}
return state, nil
}
// WorkspacePreparationStatus reads only the last recorded readiness state.
// Actual source and environment fingerprints are checked before every use.
func (e *Engine) WorkspacePreparationStatus(ctx context.Context, id string) (runtime.WorkspacePreparationStatus, error) {
run, ok := e.repo.RunState(id)
if !ok {
return runtime.WorkspacePreparationStatus{}, fmt.Errorf("运行不存在")
}
if e.defaultExecutionRunner(run) != "" || e.foreignWorkspaceBind(run) {
return e.remoteWorkspacePreparation(ctx, run, domain.RunnerWorkspaceOperationPreparationStatus)
}
root, reason := e.LocalRunWorkspace(run)
if reason != "" {
return runtime.WorkspacePreparationStatus{Status: "unprepared", Steps: []runtime.WorkspacePreparationStep{}}, nil
}
e.runEnvMu.Lock()
scopeEnv := e.runEnvs[id]
e.runEnvMu.Unlock()
if scopeEnv == nil {
return runtime.WorkspacePreparationStatus{Status: "unprepared", Error: "执行环境尚未检查;文件仍可浏览", Steps: []runtime.WorkspacePreparationStep{}}, nil
}
state := runtime.ReadWorkspacePreparationStatus(root, scopeEnv.ID())
if state.Status == "preparing" {
e.runEnvMu.Lock()
env := e.runEnvs[id]
active := env != nil && env.preparing.Load()
e.runEnvMu.Unlock()
if !active {
state.Status = "unprepared"
state.Error = "上次工作区准备已中断,请重新准备"
}
}
if state.Status == "ready" {
e.runEnvMu.Lock()
env := e.runEnvs[id]
e.runEnvMu.Unlock()
reason := ""
if env == nil {
reason = "执行环境尚未检查;文件仍可浏览"
} else {
epoch, err := runtime.ReadSandboxEnvironmentIdentity(ctx, env.sandbox)
if err != nil || !runtime.WorkspacePreparationReusable(state, workspacePreparationPlan(run), run.RepositoryContexts(), epoch) {
reason = "执行环境或准备配置已变化,需要重新准备"
}
}
if reason != "" {
state.Status = "unprepared"
state.Error = reason
for i := range state.Steps {
state.Steps[i].Status = "unprepared"
}
return state, nil
}
}
return state, nil
}
// EnsureWorkspaceReady establishes the execution environment after file
// restoration. It deliberately leaves the run outcome and node history intact.
func (e *Engine) EnsureWorkspaceReady(ctx context.Context, id string) (runtime.WorkspacePreparationStatus, error) {
run, ok := e.repo.RunState(id)
if !ok {
return runtime.WorkspacePreparationStatus{}, fmt.Errorf("运行不存在")
}
if e.defaultExecutionRunner(run) != "" || e.foreignWorkspaceBind(run) {
return e.remoteWorkspacePreparation(ctx, run, domain.RunnerWorkspaceOperationPrepare)
}
env, err := e.acquireConversationEnvironment(ctx, run)
if err != nil {
return runtime.WorkspacePreparationStatus{Status: "failed", Error: err.Error(), Steps: []runtime.WorkspacePreparationStep{}}, err
}
env.nodeMu.Lock()
defer env.nodeMu.Unlock()
if current, ok := e.repo.RunState(id); ok {
run = current
}
if run.HasActiveNode() || env.activeExecutions.Load() > 0 || e.workspaceTerminals.HasRunScope(id) || e.WorkspaceActive != nil && e.WorkspaceActive(run) {
state := runtime.ReadWorkspacePreparationStatus(env.Workspace(), env.ID())
epoch, err := runtime.ReadSandboxEnvironmentIdentity(ctx, env.sandbox)
// The environment agents already run in serves the IDE terminal too.
if err == nil && runtime.WorkspacePreparationReusable(state, workspacePreparationPlan(run), run.RepositoryContexts(), epoch) {
return state, nil
}
if state.Status != "preparing" && runtime.WorkspacePreparationTrivial(workspacePreparationPlan(run)) {
return runtime.WorkspacePreparationStatus{Status: "ready", Steps: []runtime.WorkspacePreparationStep{}}, nil
}
return runtime.WorkspacePreparationStatus{Status: "unprepared", Error: "成员或终端正在使用工作区,请结束当前操作后重新准备", Steps: []runtime.WorkspacePreparationStep{}}, fmt.Errorf("成员或终端正在使用工作区,请结束当前操作后重新准备")
}
return e.prepareLocalEnvironment(ctx, run, env)
}
func (e *Engine) PrepareNodeWorkspace(ctx context.Context, run domain.Run, env *runEnvironment) (runtime.WorkspacePreparationStatus, error) {
if len(runtime.PreparationNodes(runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot))) == 0 {
return runtime.WorkspacePreparationStatus{Status: "ready", Steps: []runtime.WorkspacePreparationStep{}}, nil
}
if e.defaultExecutionRunner(run) != "" {
if run.IsWorkspace() {
if current, ok := e.repo.RunState(run.ID); ok {
run = current
}
}
// A sibling branch, group role, finishing task or snapshot may hold the
// runner fence for a moment (or for its whole preparation). That is a
// reason to wait, never to fail this node.
return e.waitWorkspaceNotBusy(ctx, run, func(run domain.Run) (runtime.WorkspacePreparationStatus, error) {
if run.IsWorkspace() {
state, statusErr := e.remoteWorkspacePreparation(ctx, run, domain.RunnerWorkspaceOperationPreparationStatus)
if statusErr == nil && state.Status == "ready" {
return state, nil
}
}
return e.remoteWorkspacePreparation(ctx, run, domain.RunnerWorkspaceOperationPrepare)
})
}
if run.IsWorkspace() && env.activeExecutions.Load() > 0 {
state := runtime.ReadWorkspacePreparationStatus(env.Workspace(), env.ID())
epoch, err := runtime.ReadSandboxEnvironmentIdentity(ctx, env.sandbox)
if err == nil && runtime.WorkspacePreparationReusable(state, workspacePreparationPlan(run), run.RepositoryContexts(), epoch) {
return state, nil
}
return state, fmt.Errorf("正在协作的工作区环境发生变化,请等待当前分工结束后重新准备")
}
return e.prepareLocalEnvironment(ctx, run, env)
}
// HandleWorkspaceTerminal uses exactly the same environment and preparation
// contract as SOP execution. The pool owns the PTY, the Engine owns the sandbox.
func (e *Engine) HandleWorkspaceTerminal(ctx context.Context, id string, pool *runtime.TerminalPool, scope string, req domain.WorkspaceTerminalRequest, actorID int64) (runtime.TerminalResult, error) {
if req.Operation == "open" {
if err := e.RestoreConversationWorkspaceIfNeeded(ctx, id); err != nil {
return runtime.TerminalResult{}, err
}
if _, err := e.EnsureWorkspaceReady(ctx, id); err != nil {
return runtime.TerminalResult{}, err
}
}
run, _ := e.repo.RunState(id)
run.ID = id
var credentials runtime.TerminalGitCredentials
if req.Operation == "open" {
credentials = e.WorkspaceTerminalGitCredentials(ctx, run, actorID)
}
return e.HandlePreparedWorkspaceTerminal(ctx, run, pool, scope, req, credentials)
}
// WorkspaceTerminalGitCredentials resolves the opening user's credentials before
// acquiring an editor transaction on the run.
func (e *Engine) WorkspaceTerminalGitCredentials(ctx context.Context, run domain.Run, actorID int64) runtime.TerminalGitCredentials {
if actorID <= 0 {
return runtime.TerminalGitCredentials{}
}
return runtime.TerminalGitCredentials{
HTTPS: e.repo.GitHTTPCredentialSecrets(ctx, actorID),
SSHKeys: e.repo.GitSSHKeysForRemotes(actorID, sshRepositoryURLs(run.RepositoryContexts())),
}
}
// HandlePreparedWorkspaceTerminal takes the run from its caller, which may
// hold the run row locked: reading it again here would wait on that lock.
// The run must carry its node states (RunState, not a bare locked row):
// without them every succeeded preparation step looks pending and the
// readiness check would be skipped as if there were nothing to prepare.
func (e *Engine) HandlePreparedWorkspaceTerminal(ctx context.Context, run domain.Run, pool *runtime.TerminalPool, scope string, req domain.WorkspaceTerminalRequest, credentials runtime.TerminalGitCredentials) (runtime.TerminalResult, error) {
id := run.ID
if req.Operation != "open" {
return pool.HandleSandbox(ctx, nil, scope, req, nil)
}
e.runEnvMu.Lock()
env := e.runEnvs[id]
e.runEnvMu.Unlock()
if env == nil {
return runtime.TerminalResult{}, fmt.Errorf("工作区环境尚未准备,请重新打开终端")
}
state := runtime.ReadWorkspacePreparationStatus(env.Workspace(), env.ID())
epoch, err := runtime.ReadSandboxEnvironmentIdentity(ctx, env.sandbox)
trivial := len(run.WorkflowSnapshot.Nodes) > 0 && runtime.WorkspacePreparationTrivial(workspacePreparationPlan(run))
if !trivial && (err != nil || state.Status != "ready" || state.Environment != epoch) {
return runtime.TerminalResult{}, fmt.Errorf("工作区执行环境已变化,请重新准备后打开终端")
}
return pool.HandleSandboxWithGit(ctx, env.sandbox, scope, req, nil, credentials)
}
// TrustedWorkspaceRequest attaches frozen execution configuration to an
// authenticated workspace transport. It is never exposed as user-controlled configuration.
func (e *Engine) TrustedWorkspaceRequest(id string, request domain.RunnerWorkspaceRequest) (domain.RunnerWorkspaceRequest, error) {
run, ok := e.repo.RunState(id)
if !ok {
return request, fmt.Errorf("运行不存在")
}
return e.preparedWorkspaceRequest(run, request)
}
func (e *Engine) WorkspaceRemoteHost(run domain.Run) bool { return e.foreignWorkspaceBind(run) }
func (e *Engine) ForwardWorkspaceRequest(ctx context.Context, run domain.Run, request domain.RunnerWorkspaceRequest) (domain.RunnerWorkspaceResponse, error) {
trusted, err := e.preparedWorkspaceRequest(run, request)
if err != nil {
return domain.RunnerWorkspaceResponse{}, err
}
return e.requestWorkspaceCheckpoint(ctx, run, trusted)
}
// A settled historical workflow may refer to a role removed from the catalog.
// Opening its files/terminal must not require resurrecting that model role.
// Execution still uses the strict workflow validation and executor resolution.
func workspaceConversationRequirements(st *repo.Store, wf domain.WorkflowDefinition, codexLoginRelay bool) (runtime.SandboxRequirements, error) {
var items []runtime.SandboxRequirements
for _, node := range wf.Nodes {
if node.Type != "agent" {
continue
}
agent, ok := workflowAgent(st, wf, node.AgentID)
if !ok {
continue
}
executor, err := resolveNodeExecutor(st, node, agent)
if err != nil {
continue
}
requirements := runtime.ProviderRequirements(executor.Kind)
// Freeze the relay need for the whole workflow so preparation, scripts,
// terminals and agents can reuse the same Docker container.
requirements.RunnerLoginRelay = codexLoginRelay && executor.Kind == "codex"
items = append(items, requirements)
}
return runtime.MergeSandboxRequirements(items...), nil
}
// ForwardPreparedWorkspaceRequest is used under an editor transaction after
// the caller has bound all configuration outside the run-row lock.
func (e *Engine) ForwardPreparedWorkspaceRequest(ctx context.Context, run domain.Run, request domain.RunnerWorkspaceRequest) (domain.RunnerWorkspaceResponse, error) {
run.ExecutionContext.ExecutionMode = domain.ExecutionModeCloud
return e.requestWorkspaceCheckpoint(ctx, run, request)
}
// Only scripts that already succeeded in normal SOP execution can be replayed
// to reconstruct its environment. Pending/failed/current/downstream nodes keep
// their ordinary scheduling semantics and are never executed early.
func workspacePreparationPlan(run domain.Run) domain.WorkflowDefinition {
wf := runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot)
wf.Nodes = append([]domain.WorkflowNode(nil), wf.Nodes...)
states := run.Nodes
for i := range wf.Nodes {
if !wf.Nodes[i].RunOnWorkspaceRebuild {
continue
}
state := states[wf.Nodes[i].ID]
if state == nil || state.Status != "succeeded" {
wf.Nodes[i].RunOnWorkspaceRebuild = false
}
}
wf.CollaborationMode = ""
wf.SOPCheckpoint = nil
return wf
}
func (e *Engine) recordNodeWorkspacePreparation(ctx context.Context, run domain.Run, env *runEnvironment, node domain.WorkflowNode, output string) error {
if len(output) > 32<<10 {
output = output[:32<<10]
}
if !node.RunOnWorkspaceRebuild {
return nil
}
if e.defaultExecutionRunner(run) != "" {
request, err := e.preparedWorkspaceRequest(run, domain.RunnerWorkspaceRequest{RunID: run.ID, Operation: domain.RunnerWorkspaceOperationPreparationRecord, PreparationNodeID: node.ID, PreparationOutput: output})
if err != nil {
return err
}
response, err := e.requestWorkspaceCheckpoint(ctx, run, request)
if err != nil {
return err
}
if response.Error != "" {
return fmt.Errorf("记录工作区重建步骤失败:%s", response.Error)
}
return nil
}
// The receipt is read-modify-written; parallel branches no longer hold
// nodeMu while executing, so take it for the record itself.
env.nodeMu.Lock()
defer env.nodeMu.Unlock()
_, err := runtime.RecordWorkspacePreparation(ctx, env.sandbox, runtime.WorkspacePreparationWorkflow(run.WorkflowSnapshot), run.RepositoryContexts(), node.ID, output)
return err
}