Reaction Configuration

Auto-responses to CI failures, review comments, and agent events

Reactions are the core automation mechanism in Agent Orchestrator. They define how the system responds to events like CI failures, review comments, and agent state changes—automatically handling routine issues without human intervention.

Reaction System Overview

When an event occurs (e.g., CI fails, review requested), the orchestrator:

1. Check Reaction Config

   Looks up the reaction configuration for the event type

2. Auto-Handle

   If auto: true, performs the configured action automatically

3. Escalate

   If retries exhausted or timeout reached, escalates to human notification

Push, not pull. The human never needs to check on agents—the orchestrator notifies when judgment is required.

Source: packages/core/src/lifecycle-manager.ts:422-498

Built-in Reactions

Agent Orchestrator includes 8 built-in reactions with sensible defaults:

ci-failed

Triggered when CI checks fail on a PR.

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: "CI is failing on your PR. Run `gh pr checks` to see the failures, fix them, and push."
    retries: 2
    escalateAfter: 2  # Escalate to human after 2 failures

auto · boolean · default: "true"

Enable automatic handling

action · enum · default: "send-to-agent"

What to do when CI fails:

• send-to-agent — Send failure info to agent to fix
• notify — Immediately notify human

retries · number · default: "2"

How many times to let the agent retry before escalating

escalateAfter · number

Escalate to human after this many failures

changes-requested

Triggered when a reviewer requests changes.

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    message: "There are review comments on your PR. Check with `gh pr view --comments` and `gh api` for inline comments. Address each one, push fixes, and reply."
    escalateAfter: 30m  # Escalate if not resolved in 30 minutes

escalateAfter · string

Time-based escalation. Supports: 10m, 1h, 30m

The agent automatically fetches review comments and attempts to address them. Only escalates to human if it can’t resolve within the time limit.

bugbot-comments

Triggered when automated review tools (linters, security scanners) leave comments.

reactions:
  bugbot-comments:
    auto: true
    action: send-to-agent
    message: "Automated review comments found on your PR. Fix the issues flagged by the bot."
    escalateAfter: 30m

Detects bot comments from common tools:

• GitHub Actions annotations
• ESLint reporters
• Security scanners
• Coverage reporters

merge-conflicts

Triggered when the PR branch has merge conflicts with the base branch.

reactions:
  merge-conflicts:
    auto: true
    action: send-to-agent
    message: "Your branch has merge conflicts. Rebase on the default branch and resolve them."
    escalateAfter: 15m

The agent will attempt to rebase and resolve conflicts. Complex conflicts may require human intervention.

approved-and-green

Triggered when PR is approved by reviewers AND CI passes.

reactions:
  approved-and-green:
    auto: false  # Disabled by default — requires explicit opt-in
    action: notify
    priority: action
    message: "PR is ready to merge"

Auto-merge is disabled by default for safety. Enable only if you have:

• Comprehensive CI/CD tests
• Required code review approval
• High confidence in agent code quality

To enable auto-merge:

reactions:
  approved-and-green:
    auto: true  # Enable auto-merge
    action: auto-merge  # Change action from notify to auto-merge

See Auto-Merge Configuration below for details.

agent-stuck

Triggered when agent shows no activity for a duration.

reactions:
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m  # Consider stuck after 10 minutes idle

threshold · string · default: "10m"

Duration of inactivity before considering agent “stuck”

Sends urgent notification to human to investigate.

agent-needs-input

Triggered when agent asks a question or hits a permission prompt.

reactions:
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent

Examples:

• “Should I proceed with this refactoring?”
• Permission prompt for file operations
• Confirmation needed for destructive changes

agent-exited

Triggered when agent process exits unexpectedly.

reactions:
  agent-exited:
    auto: true
    action: notify
    priority: urgent

Causes:

• Agent crashed
• Out of memory
• Unhandled error
• Manual termination

all-complete

Triggered when all spawned agents finish their work.

reactions:
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true

includeSummary · boolean · default: "true"

Include summary of all sessions in the notification

Source: packages/core/src/config.ts:215-278

Reaction Configuration Schema

All reactions support these fields:

auto · boolean · required

Enable automatic handling. If false, the reaction is disabled.

action · enum · required

What action to take:

• send-to-agent — Send message to agent to handle
• notify — Send notification to human
• auto-merge — Automatically merge the PR (only for approved-and-green)

message · string

Custom message to send to agent (for send-to-agent action) or human (for notify action).

priority · enum

Notification priority level:

• urgent — Critical issues requiring immediate attention
• action — Action required but not urgent
• warning — Something to be aware of
• info — Informational only

Controls which notifiers receive the message (see Notification Routing).

retries · number

How many times to retry send-to-agent before escalating to human.

escalateAfter · number | string

Escalation condition:

• Number: Escalate after this many failures (e.g., 2 = after 2 failed attempts)
• String: Escalate after this duration (e.g., 30m, 1h)

threshold · string

Duration threshold for time-based triggers (e.g., agent-stuck).

Examples: 10m, 30m, 1h

includeSummary · boolean

Include summary of all sessions in the notification (for all-complete).

Source: packages/core/src/types.ts:763-788

Global Reaction Configuration

Define default reaction behavior for all projects:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3  # More aggressive retry
    escalateAfter: 3
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h  # Give agent more time
  
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 15m  # More lenient stuck detection

Per-Project Reaction Overrides

Override global reactions for specific projects:

# Global defaults
reactions:
  approved-and-green:
    auto: false  # Auto-merge disabled globally
    action: notify

projects:
  # Trusted project: enable auto-merge
  frontend:
    repo: org/frontend
    path: ~/frontend
    reactions:
      approved-and-green:
        auto: true  # Override: enable auto-merge for this project
        action: auto-merge
  
  # High-risk project: more conservative
  payment-service:
    repo: org/payment-service
    path: ~/payment-service
    reactions:
      ci-failed:
        auto: false  # Override: disable auto-fix, always notify human
        action: notify
        priority: urgent

Per-project reactions merge with global reactions. You only need to specify the fields you want to override.

Auto-Merge Configuration

Auto-merge is the most aggressive automation option. Use with caution.

Requirements for Auto-Merge

Before enabling auto-merge, ensure:

1. Comprehensive CI

   Your CI pipeline includes:

   • Unit tests
   • Integration tests
   • Linting
   • Type checking
   • Security scanning
2. Required Approvals

   GitHub branch protection requires:

   • At least one approval
   • Passing CI checks
   • Up-to-date branch
3. Agent Trust

   You’ve validated agent quality on several PRs manually first.

Enable Auto-Merge Globally

reactions:
  approved-and-green:
    auto: true
    action: auto-merge
    priority: info  # Notify after merge completes

Enable Auto-Merge per Project

projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    reactions:
      approved-and-green:
        auto: true
        action: auto-merge

Disable Auto-Merge (Default)

reactions:
  approved-and-green:
    auto: false  # Disabled (default)
    action: notify
    priority: action
    message: "PR is ready to merge"

With auto-merge disabled, you’ll receive an “action” priority notification when PRs are ready, and merge them manually.

Source: examples/auto-merge.yaml

Escalation Rules

Escalation determines when to notify a human after automatic handling fails.

Retry-Based Escalation

Escalate after a number of failed attempts:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3  # Notify human after 3 failed fix attempts

Flow:

1. CI fails → agent attempts fix #1
2. Still failing → agent attempts fix #2
3. Still failing → agent attempts fix #3
4. Still failing → escalate to human (urgent notification)

Time-Based Escalation

Escalate after a duration:

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m  # Notify human if unresolved in 30 minutes

Flow:

1. Review comments received → agent starts addressing
2. Timer starts (30 minutes)
3. If agent resolves within 30m → no escalation
4. If unresolved after 30m → escalate to human (urgent notification)

Mixed Escalation

Combine both approaches:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 5
    escalateAfter: 1h  # Escalate after 5 failures OR 1 hour, whichever comes first

Custom Reaction Messages

Override default messages:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: |
      CI checks are failing. Please:
      1. Run `gh pr checks` to see failures
      2. Run tests locally: `pnpm test`
      3. Fix the issues and push
      4. Verify CI passes
    retries: 2

Custom messages for notifications:

reactions:
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "🎉 PR approved and CI green! Ready to merge: {{prUrl}}"

Messages support template variables like {{prUrl}}, {{sessionId}}, {{projectId}}.

Disabling Reactions

Disable a reaction by setting auto: false:

reactions:
  changes-requested:
    auto: false  # Disable automatic handling
    action: notify  # Always notify human immediately
    priority: action

When disabled, the orchestrator immediately notifies humans instead of attempting automatic handling.

Testing Reactions

Test your reaction configuration:

# Spawn an agent on a test issue
ao spawn my-app TEST-123

# Watch the dashboard
ao status

# Trigger events manually:
# - Push a failing commit (to trigger ci-failed)
# - Request changes on the PR (to trigger changes-requested)
# - Approve the PR (to trigger approved-and-green)

Monitor logs to see reaction behavior:

# Check orchestrator logs
tail -f ~/.agent-orchestrator/logs/orchestrator.log

Complete Example

A production-ready reaction configuration:

reactions:
  # Auto-fix CI failures with retries
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3
  
  # Auto-address review comments with timeout
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 45m
  
  # Auto-fix bot comments
  bugbot-comments:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  
  # Auto-resolve merge conflicts
  merge-conflicts:
    auto: true
    action: send-to-agent
    escalateAfter: 20m
  
  # Notify when ready (auto-merge disabled for safety)
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "PR ready to merge"
  
  # Notify when agent is stuck
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 12m
  
  # Urgent notification when agent needs input
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
  
  # Urgent notification on agent crash
  agent-exited:
    auto: true
    action: notify
    priority: urgent
  
  # Summary when all done
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true

Next Steps

Notifications

Configure how reactions notify you via Slack, Discord, etc.

Projects

Set up per-project reaction overrides