Enum Effect 

pub enum Effect {
    AgentInvocation {
        role: AgentRole,
        agent: String,
        model: Option<String>,
        prompt: String,
    },
    InitializeAgentChain {
        drain: AgentDrain,
    },
    PreparePlanningPrompt {
        iteration: u32,
        prompt_mode: PromptMode,
    },
    MaterializePlanningInputs {
        iteration: u32,
    },
    CleanupRequiredFiles {
        files: Box<[String]>,
    },
    InvokePlanningAgent {
        iteration: u32,
    },
    ExtractPlanningXml {
        iteration: u32,
    },
    ValidatePlanningXml {
        iteration: u32,
    },
    WritePlanningMarkdown {
        iteration: u32,
    },
    ArchivePlanningXml {
        iteration: u32,
    },
    ApplyPlanningOutcome {
        iteration: u32,
        valid: bool,
    },
    PrepareDevelopmentContext {
        iteration: u32,
    },
    MaterializeDevelopmentInputs {
        iteration: u32,
    },
    PrepareDevelopmentPrompt {
        iteration: u32,
        prompt_mode: PromptMode,
    },
    InvokeDevelopmentAgent {
        iteration: u32,
    },
    InvokeAnalysisAgent {
        iteration: u32,
    },
    ExtractDevelopmentXml {
        iteration: u32,
    },
    ValidateDevelopmentXml {
        iteration: u32,
    },
    ApplyDevelopmentOutcome {
        iteration: u32,
    },
    ArchiveDevelopmentXml {
        iteration: u32,
    },
    PrepareReviewContext {
        pass: u32,
    },
    MaterializeReviewInputs {
        pass: u32,
    },
    PrepareReviewPrompt {
        pass: u32,
        prompt_mode: PromptMode,
    },
    InvokeReviewAgent {
        pass: u32,
    },
    ExtractReviewIssuesXml {
        pass: u32,
    },
    ValidateReviewIssuesXml {
        pass: u32,
    },
    WriteIssuesMarkdown {
        pass: u32,
    },
    ExtractReviewIssueSnippets {
        pass: u32,
    },
    ArchiveReviewIssuesXml {
        pass: u32,
    },
    ApplyReviewOutcome {
        pass: u32,
        issues_found: bool,
        clean_no_issues: bool,
    },
    PrepareFixPrompt {
        pass: u32,
        prompt_mode: PromptMode,
    },
    InvokeFixAgent {
        pass: u32,
    },
    InvokeFixAnalysisAgent {
        pass: u32,
    },
    ExtractFixResultXml {
        pass: u32,
    },
    ValidateFixResultXml {
        pass: u32,
    },
    ApplyFixOutcome {
        pass: u32,
    },
    ArchiveFixResultXml {
        pass: u32,
    },
    RunRebase {
        phase: RebasePhase,
        target_branch: String,
    },
    ResolveRebaseConflicts {
        strategy: ConflictStrategy,
    },
    CheckCommitDiff,
    PrepareCommitPrompt {
        prompt_mode: PromptMode,
    },
    MaterializeCommitInputs {
        attempt: u32,
    },
    InvokeCommitAgent,
    ExtractCommitXml,
    ValidateCommitXml,
    ApplyCommitMessageOutcome,
    ArchiveCommitXml,
    CreateCommit {
        message: String,
        files: Vec<String>,
        excluded_files: Vec<ExcludedFile>,
    },
    SkipCommit {
        reason: String,
    },
    CheckResidualFiles {
        pass: u8,
    },
    CheckUncommittedChangesBeforeTermination,
    BackoffWait {
        role: AgentRole,
        cycle: u32,
        duration_ms: u64,
    },
    ReportAgentChainExhausted {
        role: AgentRole,
        phase: PipelinePhase,
        cycle: u32,
    },
    ValidateFinalState,
    SaveCheckpoint {
        trigger: CheckpointTrigger,
    },
    EnsureGitignoreEntries,
    CleanupContext,
    RestorePromptPermissions,
    LockPromptPermissions,
    WriteContinuationContext(ContinuationContextData),
    CleanupContinuationContext,
    WriteTimeoutContext {
        role: AgentRole,
        logfile_path: String,
        context_path: String,
    },
    TriggerDevFixFlow {
        failed_phase: PipelinePhase,
        failed_role: AgentRole,
        retry_cycle: u32,
    },
    EmitCompletionMarkerAndTerminate {
        is_failure: bool,
        reason: Option<String>,
    },
    TriggerLoopRecovery {
        detected_loop: String,
        loop_count: u32,
    },
    EmitRecoveryReset {
        reset_type: RecoveryResetType,
        target_phase: PipelinePhase,
    },
    AttemptRecovery {
        level: u32,
        attempt_count: u32,
    },
    EmitRecoverySuccess {
        level: u32,
        total_attempts: u32,
    },
    CheckNetworkConnectivity,
    PollForConnectivity {
        interval_ms: u64,
    },
    ConfigureGitAuth {
        auth_method: String,
    },
    PushToRemote {
        remote: String,
        branch: String,
        force: bool,
        commit_sha: String,
    },
    CreatePullRequest {
        base_branch: String,
        head_branch: String,
        title: String,
        body: String,
    },
}

Effects represent side-effect operations.

The reducer determines which effect to execute next based on state. Effect handlers execute effects and emit events.

Variants

AgentInvocation

Fields

role: AgentRole

agent: String

model: Option<String>

prompt: String

InitializeAgentChain

Resolve and materialize the concrete chain bound to a built-in runtime drain.

The reducer/orchestrator addresses drains directly so handlers never need to reconstruct chain selection from compatibility role metadata at invocation time.

Fields

drain: AgentDrain

PreparePlanningPrompt

Prepare the planning prompt for an iteration (single-task).

Fields

iteration: u32

prompt_mode: PromptMode

MaterializePlanningInputs

Materialize planning inputs, handling oversize inline vs file references (single-task).

Fields

iteration: u32

CleanupRequiredFiles

Delete specified files from the workspace to ensure fresh agent output (single-task).

XSD retry exemption: skipped on attempt > 1 so the agent can read the previous invalid XML (see XSD retry prompts for details).

Fields

files: Box<[String]>

Files to delete (paths relative to workspace root).

InvokePlanningAgent

Invoke the planning agent for an iteration (single-task).

Fields

iteration: u32

ExtractPlanningXml

Verify that .agent/tmp/plan.xml exists and is readable (single-task).

Fields

iteration: u32

ValidatePlanningXml

Validate/parse the XML at .agent/tmp/plan.xml and emit a planning validation event (single-task).

Fields

iteration: u32

WritePlanningMarkdown

Write .agent/PLAN.md from the validated planning XML (single-task).

Fields

iteration: u32

ArchivePlanningXml

Archive .agent/tmp/plan.xml after PLAN.md is written (single-task).

Fields

iteration: u32

ApplyPlanningOutcome

Emit the appropriate planning outcome event (single-task).

Fields

iteration: u32

valid: bool

PrepareDevelopmentContext

Write context artifacts needed for the development prompt (single-task).

Fields

iteration: u32

MaterializeDevelopmentInputs

Materialize development inputs, handling oversize inline vs file references (single-task).

Fields

iteration: u32

PrepareDevelopmentPrompt

Prepare the development prompt for an iteration (single-task).

Fields

iteration: u32

prompt_mode: PromptMode

InvokeDevelopmentAgent

Invoke the developer agent for an iteration (single-task).

Fields

iteration: u32

InvokeAnalysisAgent

Invoke the analysis agent to assess git diff against PLAN.md (single-task).

Produces development_result.xml. Does not parse or validate outputs.

Fields

iteration: u32

ExtractDevelopmentXml

Verify that .agent/tmp/development_result.xml exists and is readable (single-task).

Fields

iteration: u32

ValidateDevelopmentXml

Validate/parse the XML at .agent/tmp/development_result.xml (single-task).

Fields

iteration: u32

ApplyDevelopmentOutcome

Emit the appropriate development outcome event (single-task).

Fields

iteration: u32

ArchiveDevelopmentXml

Archive .agent/tmp/development_result.xml after validation (single-task).

Fields

iteration: u32

PrepareReviewContext

Write review inputs (prompt backups, diffs, etc.) for the reviewer agent (single-task).

Fields

pass: u32

MaterializeReviewInputs

Materialize review inputs, handling oversize inline vs file references (single-task).

Fields

pass: u32

PrepareReviewPrompt

Prepare the review prompt for a pass (single-task).

Fields

pass: u32

prompt_mode: PromptMode

InvokeReviewAgent

Invoke the reviewer agent for a review pass (single-task).

Fields

pass: u32

ExtractReviewIssuesXml

Verify that .agent/tmp/issues.xml exists and is readable (single-task).

Fields

pass: u32

ValidateReviewIssuesXml

Validate/parse the XML at .agent/tmp/issues.xml (single-task).

Fields

pass: u32

WriteIssuesMarkdown

Write .agent/ISSUES.md from the validated issues XML (single-task).

Fields

pass: u32

ExtractReviewIssueSnippets

Extract review issue snippets and emit UI output (single-task).

Fields

pass: u32

ArchiveReviewIssuesXml

Archive .agent/tmp/issues.xml after ISSUES.md is written (single-task).

Fields

pass: u32

ApplyReviewOutcome

Emit the appropriate review outcome event (single-task).

Fields

pass: u32

issues_found: bool

clean_no_issues: bool

PrepareFixPrompt

Prepare the fix prompt for a review pass (single-task).

Fields

pass: u32

prompt_mode: PromptMode

InvokeFixAgent

Invoke the fix agent for a review pass (single-task).

Fields

pass: u32

InvokeFixAnalysisAgent

Invoke the fix analysis agent to verify fix results (single-task).

This runs after every fix agent invocation to independently verify whether the fix addressed the review issues. Uses the same drain as development analysis (AgentDrain::Analysis).

Fields

pass: u32

ExtractFixResultXml

Verify that .agent/tmp/fix_result.xml exists and is readable (single-task).

Fields

pass: u32

ValidateFixResultXml

Validate/parse the XML at .agent/tmp/fix_result.xml (single-task).

Fields

pass: u32

ApplyFixOutcome

Emit the appropriate fix outcome event (single-task).

Fields

pass: u32

ArchiveFixResultXml

Archive .agent/tmp/fix_result.xml after validation (single-task).

Intentionally sequenced before ApplyFixOutcome so the reducer can archive artifacts while still in the fix chain.

Fields

pass: u32

RunRebase

Fields

phase: RebasePhase

target_branch: String

ResolveRebaseConflicts

Fields

strategy: ConflictStrategy

CheckCommitDiff

Compute/write the commit diff and emit whether it is empty (single-task).

PrepareCommitPrompt

Render/write the commit prompt for the subsequent commit agent invocation (single-task).

Fields

prompt_mode: PromptMode

MaterializeCommitInputs

Materialize commit inputs, handling model-budget truncation and inline vs reference (single-task).

Fields

attempt: u32

InvokeCommitAgent

Invoke the commit agent (single-task).

ExtractCommitXml

Verify that .agent/tmp/commit_message.xml exists and is readable (single-task).

ValidateCommitXml

Validate/parse the XML at .agent/tmp/commit_message.xml (single-task).

ApplyCommitMessageOutcome

Emit the appropriate commit outcome event (single-task).

ArchiveCommitXml

Archive .agent/tmp/commit_message.xml after validation (single-task).

CreateCommit

Fields

message: String

files: Vec<String>

Files to selectively stage. Empty means stage all changed files.

excluded_files: Vec<ExcludedFile>

Files excluded from this commit with their reasons.

Audit/observability only — must not change commit execution semantics. Defaults to empty for backward compatibility with old checkpoints.

SkipCommit

Fields

reason: String

CheckResidualFiles

After a selective commit pass, check whether any staged/unstaged files remain.

Emits ResidualFilesFound { files, pass } if the working tree is still dirty, or ResidualFilesNone when it is clean. pass identifies which commit pass just completed (1 = first selective commit, 2 = second/final pass).

Fields

pass: u8

Which commit pass just completed (1-indexed).

CheckUncommittedChangesBeforeTermination

Run git status --porcelain before termination; route to commit phase if changes exist (single-task).

User-initiated Ctrl+C (interrupted_by_user=true) skips this check.

BackoffWait

Wait for a retry-cycle backoff delay.

Fields

role: AgentRole

cycle: u32

duration_ms: u64

ReportAgentChainExhausted

Report that the agent chain has exhausted all retry attempts.

Fields

role: AgentRole

phase: PipelinePhase

cycle: u32

ValidateFinalState

SaveCheckpoint

Fields

trigger: CheckpointTrigger

EnsureGitignoreEntries

Check .gitignore for required entries and add any missing ones (single-task).

CleanupContext

RestorePromptPermissions

Restore PROMPT.md write permissions after pipeline completion.

LockPromptPermissions

Lock PROMPT.md with read-only permissions at pipeline startup.

WriteContinuationContext(ContinuationContextData)

Write continuation context file for the next development attempt.

CleanupContinuationContext

Clean up continuation context file when iteration completes or a fresh iteration starts.

WriteTimeoutContext

Preserve prior agent context to a temp file when a timeout occurs without session IDs.

Fields

role: AgentRole

The role this agent is fulfilling.

logfile_path: String

Source logfile path to extract context from.

context_path: String

Target temp file path for context (e.g., .agent/tmp/timeout_context_1.txt).

TriggerDevFixFlow

Invoke the dev agent to diagnose and fix a pipeline failure (single-task).

Fields

failed_phase: PipelinePhase

The phase where the failure occurred.

failed_role: AgentRole

The role of the exhausted agent chain.

retry_cycle: u32

Retry cycle count when exhaustion occurred.

EmitCompletionMarkerAndTerminate

Write a completion marker and transition to Interrupted.

Fields

is_failure: bool

Whether the pipeline is terminating due to failure.

reason: Option<String>

Optional reason for termination.

TriggerLoopRecovery

Reset XSD retry state and loop detection counters when a tight loop is detected.

Fields

detected_loop: String

String representation of the detected loop (for diagnostics).

loop_count: u32

Number of times the loop was repeated.

EmitRecoveryReset

Emit recovery reset events to escalate recovery strategy.

Fields

reset_type: RecoveryResetType

Type of reset to perform.

target_phase: PipelinePhase

Target phase to reset to.

AttemptRecovery

Emit RecoveryAttempted event to transition back to the failed phase for retry.

Fields

level: u32

The escalation level being attempted.

attempt_count: u32

The attempt count.

EmitRecoverySuccess

Emit RecoverySucceeded event to clear recovery state after successful work completion.

Fields

level: u32

The escalation level that succeeded.

total_attempts: u32

Total attempts before success.

CheckNetworkConnectivity

One-time connectivity probe triggered immediately after a Network-class agent failure.

Probes network connectivity using TCP connections to known-good hosts.

• If online: emits AgentEvent::ConnectivityCheckSucceeded
• If offline: emits AgentEvent::ConnectivityCheckFailed

The reducer processes these events to update ConnectivityState.

PollForConnectivity

Polling effect emitted repeatedly while offline to wait for connectivity restoration.

Each execution:

1. Sleeps for interval_ms (default 5000ms)
2. Probes network connectivity
3. If still offline: emits AgentEvent::ConnectivityCheckFailed
4. If back online: emits AgentEvent::ConnectivityCheckSucceeded

The orchestrator re-derives this effect each cycle while is_offline=true, providing debounced polling without handler-side loops.

Fields

interval_ms: u64

Milliseconds to wait between polls (default: 5000).

ConfigureGitAuth

Configure git authentication for remote operations (cloud mode only).

Fields

auth_method: String

Serialized authentication method for logging/debugging.

PushToRemote

Push commits to remote repository immediately after CreateCommit (cloud mode only).

Fields

remote: String

Remote name (e.g., “origin”)

branch: String

Branch to push

force: bool

Whether to force push

commit_sha: String

The commit SHA being pushed (for reporting)

CreatePullRequest

Create a pull request on the remote platform during Finalizing phase (cloud mode only).

Fields

base_branch: String

Target branch for the PR

head_branch: String

Source branch (the pushed branch)

title: String

PR title

body: String

PR body/description

Implementations

impl Effect

pub const fn is_same_agent_retry(&self) -> bool

Check whether this effect is a same-agent retry prompt (any phase).

Returns true for any Prepare*Prompt variant whose prompt_mode is PromptMode::SameAgentRetry. This is used by tests and diagnostics to verify that transient failures produce the correct retry behavior.

Trait Implementations

impl Clone for Effect

fn clone(&self) -> Effect

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Effect

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Effect

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Effect

fn eq(&self, other: &Effect) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Effect

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Effect

impl StructuralPartialEq for Effect