parallelrun

package
v0.2.14 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 15, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrCyclicDependencies = errors.New("cyclic task dependencies")

ErrCyclicDependencies identifies a task dependency cycle.

View Source
var ErrMissingDependency = errors.New("missing task dependency")

ErrMissingDependency identifies a dependency that references an absent task.

Functions

func IsConflictResolverSetupError

func IsConflictResolverSetupError(err error) bool

IsConflictResolverSetupError reports whether conflict resolution failed before an agent attempt could be prepared.

func IsTaskCommitScopeError

func IsTaskCommitScopeError(err error) bool

IsTaskCommitScopeError reports whether err came from produced-path scope validation.

func NewTaskCommitScopeError

func NewTaskCommitScopeError(err error) error

NewTaskCommitScopeError marks a task commit failure caused by invalid or contaminated produced-path scope metadata.

Types

type AgenticConflictResolution

type AgenticConflictResolution struct {
	// contains filtered or unexported fields
}

AgenticConflictResolution launches the configured agent through the exec prompt path and validates the resulting worktree state after each attempt.

func NewAgenticConflictResolution

func NewAgenticConflictResolution(opts ...ConflictResolutionOption) *AgenticConflictResolution

NewAgenticConflictResolution constructs the default conflict resolver.

func (*AgenticConflictResolution) Resolve

Resolve runs the selected agent for a bounded number of attempts and validates the integration worktree after every attempt.

type ConflictInput

type ConflictInput struct {
	IntegrationWorktree string
	Conflicts           ConflictSet
	Task                TaskSpec
	CommitMessage       string
	ParentRunID         string
	Attempt             int
	MaxAttempts         int
	IDE                 string
	Model               string
	ReasoningEffort     string
	ValidationCommand   []string
}

ConflictInput is the complete context for one bounded conflict-resolution cycle.

type ConflictResolutionOption

type ConflictResolutionOption func(*AgenticConflictResolution)

ConflictResolutionOption configures AgenticConflictResolution.

func WithConflictCommandRunner

func WithConflictCommandRunner(runner conflictCommandRunner) ConflictResolutionOption

WithConflictCommandRunner overrides git and validation commands for tests.

func WithConflictPreparedPromptExecutor

func WithConflictPreparedPromptExecutor(fn conflictPreparedPromptExecutor) ConflictResolutionOption

WithConflictPreparedPromptExecutor overrides the ACP exec path for tests.

func WithConflictSkillFS

func WithConflictSkillFS(skillFS fs.FS) ConflictResolutionOption

WithConflictSkillFS overrides the embedded skill source for tests.

type ConflictResolver

type ConflictResolver interface {
	Resolve(ctx context.Context, in ConflictInput) (ConflictResult, error)
}

ConflictResolver resolves an integration-branch squash conflict.

type ConflictResult

type ConflictResult struct {
	Resolved        bool
	Validated       bool
	Attempts        int
	ValidationError string
}

ConflictResult is derived after each resolver attempt from git status, conflict-marker checks, and any configured validation command.

type ConflictSet

type ConflictSet struct {
	Files       []string
	StagedFiles []string
	Clean       bool
}

ConflictSet describes a squash merge result.

type CyclicDependenciesError

type CyclicDependenciesError struct {
	Nodes []TaskID
}

CyclicDependenciesError reports the task ids participating in a dependency cycle.

func (*CyclicDependenciesError) Error

func (e *CyclicDependenciesError) Error() string

func (*CyclicDependenciesError) Unwrap

func (e *CyclicDependenciesError) Unwrap() error

Unwrap lets errors.Is match ErrCyclicDependencies.

type DependencyEdge

type DependencyEdge struct {
	From TaskID
	To   TaskID
}

DependencyEdge is a directed graph edge: From must finish before To can start.

type ExecutionOrchestrator

type ExecutionOrchestrator struct {
	// contains filtered or unexported fields
}

ExecutionOrchestrator drives the parallel task FSM happy path.

func NewParallelExecutionOrchestrator

func NewParallelExecutionOrchestrator(
	worktrees WorktreeLifecycle,
	launcher TaskLauncher,
	opts ...ExecutionOrchestratorOption,
) *ExecutionOrchestrator

NewParallelExecutionOrchestrator constructs an FSM-backed parallel orchestrator.

func (*ExecutionOrchestrator) Run

Run executes every wave, merges successful task worktrees, and fast-forwards the target branch on completion.

type ExecutionOrchestratorOption

type ExecutionOrchestratorOption func(*ExecutionOrchestrator)

ExecutionOrchestratorOption configures ExecutionOrchestrator.

func WithConflictResolver

func WithConflictResolver(resolver ConflictResolver) ExecutionOrchestratorOption

WithConflictResolver supplies the agentic merge-conflict resolver.

func WithEventEmitter

func WithEventEmitter(emitter ParallelEventEmitter) ExecutionOrchestratorOption

WithEventEmitter supplies the sink for task.parallel.* lifecycle events. When unset the orchestrator emits to a no-op sink.

func WithLogger

func WithLogger(log *slog.Logger) ExecutionOrchestratorOption

WithLogger supplies the logger used for FSM transition logs.

func WithRecoveryEventSink

func WithRecoveryEventSink(sink recovery.EventSink) ExecutionOrchestratorOption

WithRecoveryEventSink supplies the sink for run.recovery_* lifecycle events.

func WithRecoveryStrategy

func WithRecoveryStrategy(strategy recovery.RemediationStrategy) ExecutionOrchestratorOption

WithRecoveryStrategy supplies the remediation strategy used for failed tasks.

type IntegrationCleanupSpec added in v0.2.12

type IntegrationCleanupSpec struct {
	WorkspaceRoot     string
	IntegrationPath   string
	IntegrationBranch string
	BaseCommit        string
	ContentIntegrated bool
}

IntegrationCleanupSpec supplies the evidence needed to remove or preserve the integration worktree and branch.

type IntegrationSpec

type IntegrationSpec struct {
	WorkspaceRoot     string
	IntegrationPath   string
	IntegrationBranch string
	BaseRef           string
}

IntegrationSpec describes the dedicated integration branch worktree.

type MissingDependencyError

type MissingDependencyError struct {
	TaskID     TaskID
	Dependency TaskID
}

MissingDependencyError reports a dependency edge whose source task is absent.

func (*MissingDependencyError) Error

func (e *MissingDependencyError) Error() string

func (*MissingDependencyError) Unwrap

func (e *MissingDependencyError) Unwrap() error

Unwrap lets errors.Is match ErrMissingDependency.

type Outcome

type Outcome struct {
	Status            OutcomeStatus
	IntegrationBranch string
	IntegrationPath   string
	Waves             []WaveOutcome
	Tasks             []TaskOutcome
	// contains filtered or unexported fields
}

Outcome is the typed result of a parallel run.

type OutcomeStatus

type OutcomeStatus string

OutcomeStatus is the terminal status returned by the orchestrator.

const (
	ParallelOutcomeCompleted  OutcomeStatus = "completed"
	ParallelOutcomeCanceled   OutcomeStatus = "canceled"
	ParallelOutcomeFailed     OutcomeStatus = "failed"
	ParallelOutcomeRolledBack OutcomeStatus = "rolled_back"
)

type ParallelEventEmitter

type ParallelEventEmitter interface {
	EmitParallelPlanEvent(ctx context.Context, payload kinds.TaskParallelPlanPayload) error
	EmitParallelEvent(ctx context.Context, kind events.EventKind, payload kinds.TaskParallelPayload) error
}

ParallelEventEmitter publishes task.parallel.* lifecycle events for one parallel run. Implementations must be safe for use from the orchestrator goroutine. Lifecycle delivery is part of the run contract, so implementations return persistence errors to the orchestrator rather than absorbing them.

type ParallelExecutionOrchestrator

type ParallelExecutionOrchestrator = ExecutionOrchestrator

ParallelExecutionOrchestrator preserves the task-specified public API name.

type ParallelExecutionOrchestratorOption

type ParallelExecutionOrchestratorOption = ExecutionOrchestratorOption

ParallelExecutionOrchestratorOption preserves the task-specified public API name.

type ParallelOutcome

type ParallelOutcome = Outcome

ParallelOutcome preserves the task-specified public API name.

type ParallelOutcomeStatus

type ParallelOutcomeStatus = OutcomeStatus

ParallelOutcomeStatus preserves the task-specified public API name.

type ParallelPlan

type ParallelPlan = Plan

ParallelPlan preserves the task-specified public API name.

type Plan

type Plan struct {
	RunID             string
	WorkspaceRoot     string
	BaseBranch        string
	BaseCommit        string
	IntegrationBranch string
	IntegrationPath   string
	Waves             Waves
	Tasks             []TaskSpec
	Config            workspace.ParallelTasksConfig
	Recovery          workspace.AgentRecoveryConfig
}

Plan contains the complete happy-path execution input.

type PreparedTaskRun

type PreparedTaskRun interface {
	recovery.PreparedRun
	Result() TaskRunResult
	FailedConfig() *model.RuntimeConfig
}

PreparedTaskRun is the daemon-neutral task execution seam. It executes one task-scoped run and can restart the same task in the same workspace for recovery.

type StagedCommitSpec

type StagedCommitSpec struct {
	Path         string
	Message      string
	AllowedPaths []string
	StagePaths   []string
}

StagedCommitSpec constrains an integration commit to already-staged clean merge paths plus explicitly staged conflict paths.

type TaskCommitSpec

type TaskCommitSpec struct {
	Path                    string
	Message                 string
	ScopeSupported          bool
	ProducedPaths           []string
	PreExistingChangedPaths []string
	ScopeError              string
	ScopeArtifactPath       string
}

TaskCommitSpec constrains a task worktree commit to paths the child run proved it produced after its pre-agent baseline snapshot.

type TaskID

type TaskID string

TaskID is the extensionless task identity used in task dependencies.

type TaskLaunchSpec

type TaskLaunchSpec struct {
	RunID     string
	WaveIndex int
	WaveTotal int
	Task      TaskSpec
	Base      WorktreeBase
}

TaskLaunchSpec describes one isolated task run launched from a wave base.

type TaskLauncher

type TaskLauncher interface {
	PrepareTask(ctx context.Context, spec TaskLaunchSpec) (PreparedTaskRun, error)
}

TaskLauncher prepares one task-scoped worktree child run.

type TaskOutcome

type TaskOutcome struct {
	Task           TaskSpec
	WaveIndex      int
	RunID          string
	WorktreePath   string
	BaseCommit     string
	WorktreeCommit string
	WorktreeStatus string
	WorktreeReason string
	Status         TaskOutcomeStatus
	BlockedBy      TaskID
	Error          string
}

TaskOutcome records the integrated result for one task.

func (TaskOutcome) StatusReport

func (o TaskOutcome) StatusReport() string

StatusReport returns the user-facing per-task status string.

type TaskOutcomeStatus

type TaskOutcomeStatus string

TaskOutcomeStatus is the per-task status reported by the parallel run.

const (
	TaskOutcomeMerged    TaskOutcomeStatus = "merged"
	TaskOutcomeRecovered TaskOutcomeStatus = "recovered"
	TaskOutcomeFailed    TaskOutcomeStatus = "failed"
	TaskOutcomeSkipped   TaskOutcomeStatus = "skipped"
	TaskOutcomeCanceled  TaskOutcomeStatus = "canceled"
)

type TaskRunResult

type TaskRunResult struct {
	Task                    TaskSpec
	RunID                   string
	WorktreePath            string
	BaseBranch              string
	BaseCommit              string
	ScopeSupported          bool
	ProducedPaths           []string
	PreExistingChangedPaths []string
	ScopeError              string
	ScopeArtifactPath       string
}

TaskRunResult is the daemon-neutral metadata for one child task run.

type TaskSpec

type TaskSpec struct {
	ID     TaskID
	Number int
	Title  string
	Slug   string
}

TaskSpec describes one PRD task scheduled by the orchestrator.

type TaskWorktreeCleanupSpec added in v0.2.12

type TaskWorktreeCleanupSpec struct {
	WorkspaceRoot     string
	Path              string
	BaseCommit        string
	ContentIntegrated bool
}

TaskWorktreeCleanupSpec supplies the evidence needed to remove or preserve a task tree. ContentIntegrated is true only after the final branch was fast-forwarded successfully.

type WaveOutcome

type WaveOutcome struct {
	Index int
	Tasks []TaskOutcome
}

WaveOutcome records all task outcomes for one wave.

type Waves

type Waves struct {
	// contains filtered or unexported fields
}

Waves is a deterministic topological layering of task ids.

func BuildWaves

func BuildWaves(entries []model.TaskEntry) (Waves, error)

BuildWaves groups tasks into dependency-safe topological levels.

func BuildWavesFromEdges

func BuildWavesFromEdges(nodes []TaskID, edges []DependencyEdge) (Waves, error)

BuildWavesFromEdges groups explicit graph nodes and dependency edges into dependency-safe topological levels.

func (Waves) BlockedBy

func (w Waves) BlockedBy(failed map[TaskID]bool) map[TaskID]TaskID

BlockedBy returns every transitive dependent of the failed tasks mapped to the failed task that blocks it.

func (Waves) Len

func (w Waves) Len() int

Len returns the number of waves.

func (Waves) Levels

func (w Waves) Levels() [][]TaskID

Levels returns the ordered waves. The returned slices are defensive copies.

type WorktreeBase

type WorktreeBase struct {
	Branch string
	Commit string
}

WorktreeBase identifies the branch/ref a task worktree should branch from.

type WorktreeCleanupResult added in v0.2.12

type WorktreeCleanupResult struct {
	Status WorktreeCleanupStatus
	Reason string
}

WorktreeCleanupResult classifies a safe cleanup decision without turning an intentionally preserved tree into an execution failure.

type WorktreeCleanupStatus added in v0.2.12

type WorktreeCleanupStatus string

WorktreeCleanupStatus records the real post-cleanup state exposed to users.

const (
	WorktreeCleanupStatusActive    WorktreeCleanupStatus = "active"
	WorktreeCleanupStatusRemoved   WorktreeCleanupStatus = "removed"
	WorktreeCleanupStatusPreserved WorktreeCleanupStatus = "preserved"
)

type WorktreeLifecycle

type WorktreeLifecycle interface {
	CreateIntegrationBranch(ctx context.Context, spec IntegrationSpec) error
	CommitTask(ctx context.Context, spec TaskCommitSpec) (string, error)
	CommitStaged(ctx context.Context, spec StagedCommitSpec) (string, error)
	SquashMerge(ctx context.Context, integrationPath string, worktreeRef string, message string) (ConflictSet, error)
	Head(ctx context.Context, path string) (string, error)
	FastForward(ctx context.Context, workspaceRoot string, targetBranch string, integrationBranch string) error
	SyncTaskArtifacts(ctx context.Context, workspaceRoot string, tasks []TaskOutcome) error
	CleanupTaskWorktree(ctx context.Context, spec TaskWorktreeCleanupSpec) (WorktreeCleanupResult, error)
	CleanupIntegration(ctx context.Context, spec IntegrationCleanupSpec) (WorktreeCleanupResult, error)
}

WorktreeLifecycle is the orchestrator's git/write-back boundary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL