Auto-Reactions

Configure automated responses to CI failures, review comments, and PR approvals

Reactions are event handlers that run automatically when specific conditions occur. They handle routine tasks like forwarding CI failures to agents, so you only get notified when human judgment is needed.

How Reactions Work

When an event occurs:

1. Event detected

   The orchestrator detects a CI failure, review comment, approval, etc.

2. Check reaction config

   Looks up the reaction configuration for that event type

3. Execute action

   If auto: true, performs the configured action automatically

4. Escalate if needed

   If thresholds are exceeded, notifies human instead

Key principle: Push, not pull. Reactions handle routine issues automatically, and only notify you when escalation is needed.

CI Failure Handling

Automatically send CI failures to agents for fixing:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    escalateAfter: 2

Behavior:

1. CI fails on a PR
2. Orchestrator extracts failure logs
3. Sends logs + fix instructions to the agent
4. Agent fixes the issue and pushes
5. CI runs again
6. If it fails escalateAfter times, you get a notification

Aggressive (3 retries)

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3

What Agents Receive

When CI fails, the agent gets:

CI failed on your PR. Please fix the following errors:

TypeError: Cannot read property 'id' of undefined
  at validateUser (src/auth.ts:42:10)
  at processRequest (src/server.ts:120:5)

Failed tests:
  ✗ should validate user input (test/auth.test.ts:15)
  ✗ should handle missing user (test/auth.test.ts:28)

Please:
1. Fix the null reference error
2. Ensure all tests pass
3. Push your changes

Review Comment Handling

Automatically forward review comments to agents:

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m  # Escalate if not resolved in 30 minutes

Behavior:

1. Reviewer requests changes on PR
2. Orchestrator extracts review comments
3. Sends comments to agent
4. Agent addresses the feedback
5. If unresolved after escalateAfter, you get notified

Time formats for escalateAfter:

• 10m — 10 minutes
• 1h — 1 hour
• 2 — 2 retry attempts (for CI failures)
• 30m — 30 minutes

Example Review Comment Message

Reviewers requested changes on your PR:

@reviewer1 commented on src/auth.ts:42:
> This null check is insufficient. What if the user object exists
> but doesn't have an id property?
>
> Consider using optional chaining: user?.id

@reviewer2 commented on src/server.ts:120:
> Missing error handling for the async call. Should wrap in try/catch.

Please address these comments and push your changes.

Auto-Merge Configuration

Automatically merge approved PRs with passing CI:

reactions:
  approved-and-green:
    auto: true
    action: auto-merge
    priority: action

Behavior:

1. PR is approved by reviewers
2. All CI checks pass
3. Orchestrator merges the PR automatically
4. Session is cleaned up
5. You get a notification (priority: action)

Only enable auto-merge if:

• ✅ You have comprehensive CI/CD tests
• ✅ You require code review approval
• ✅ You trust your agents to write correct code
• ✅ You’re not working on critical systems (finance, healthcare)

Start with auto: false and enable after building confidence.

Conservative Auto-Merge

Notify instead of auto-merging:

reactions:
  approved-and-green:
    auto: false  # Don't auto-merge
    action: notify
    priority: action  # Send notification when ready

You’ll get notified when PRs are ready to merge, but you merge manually.

Agent Stuck Detection

Detect and notify when agents are inactive:

reactions:
  agent-stuck:
    threshold: 10m  # Consider stuck after 10 minutes of inactivity
    action: notify
    priority: urgent

Behavior:

1. Agent has no activity for threshold duration
2. Orchestrator marks session as stuck
3. You get an urgent notification
4. You can investigate and intervene

Quick timeout (5m)

reactions:
  agent-stuck:
    threshold: 5m
    action: notify
    priority: urgent

Good for fast-moving workflows where agents should respond quickly.

Patient timeout (30m)

reactions:
  agent-stuck:
    threshold: 30m
    action: notify
    priority: warning

Better for complex tasks where agents may need time to think.

Per-Project Overrides

Override global reactions for specific projects:

# Global defaults
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
  approved-and-green:
    auto: false
    action: notify

projects:
  # Critical project — no auto-merge
  backend:
    reactions:
      approved-and-green:
        auto: false
        action: notify
        priority: action
  
  # Experimental project — aggressive automation
  experiments:
    reactions:
      ci-failed:
        auto: true
        retries: 5  # More retries
      approved-and-green:
        auto: true  # Enable auto-merge
        action: auto-merge

Notification Routing

Route notifications by priority:

notificationRouting:
  urgent: [desktop, slack]     # Agent stuck, needs input, errored
  action: [desktop, slack]     # PR ready to merge
  warning: [slack]             # Auto-fix failed
  info: [slack]                # Summary, all done

Priorities:

• urgent: Requires immediate attention (agent stuck, errored)
• action: Requires action but not urgent (PR ready to merge)
• warning: Something went wrong (auto-fix failed after retries)
• info: FYI notifications (task completed, summary)

Notification Channels

Configure multiple notifiers:

notifiers:
  slack:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#agent-updates"
  
  webhook:
    plugin: webhook
    url: https://your-service.com/webhook
    method: POST

Then route by priority:

notificationRouting:
  urgent: [desktop, slack, webhook]
  action: [desktop, slack]
  warning: [slack]
  info: []

Example Configurations

Aggressive Automation (Auto-Merge Enabled)

# examples/auto-merge.yaml
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h
  
  approved-and-green:
    auto: true
    action: auto-merge
  
  agent-stuck:
    threshold: 10m
    action: notify
    priority: urgent

Use case: High-trust environment, comprehensive tests, experienced agents

Conservative (Manual Review)

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 1
    escalateAfter: 1
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 15m
  
  approved-and-green:
    auto: false  # Manual merge only
    action: notify
    priority: action
  
  agent-stuck:
    threshold: 5m
    action: notify
    priority: urgent

Use case: New to agent orchestration, building trust, critical systems

Notification-Only (No Automation)

reactions:
  ci-failed:
    auto: false
    action: notify
    priority: urgent
  
  changes-requested:
    auto: false
    action: notify
    priority: action
  
  approved-and-green:
    auto: false
    action: notify
    priority: action

Use case: Manual control, agents are learning, testing the system

Testing Reactions

Test your reaction configuration:

1. Spawn a test session

   ao spawn my-app test-reactions
   
2. Create a PR with failing tests

   Let the agent create a PR, or manually push code with test failures

3. Watch reaction trigger

   Check if the agent receives the CI failure message:

   ao open my-app-1  # Attach to see the message
   
4. Verify notification routing

   Check that notifications arrive in configured channels (Slack, desktop)

Troubleshooting

Reactions Not Triggering

Check:

1. Reaction is enabled

   reactions:
     ci-failed:
       auto: true  # Must be true
   

2. SCM plugin is configured

   projects:
     my-app:
       tracker:
         plugin: github  # Must match your platform
   

3. Webhooks are set up (for real-time events)

   GitHub webhooks are optional but recommended for immediate reactions.

Agent Not Receiving Messages

Check:

1. Session is alive

   ao status  # Check activity state
   

2. Agent can receive input

   ao send my-app-1 "test message"
   

3. Review event log

   tail -f ~/.agent-orchestrator/events.jsonl
   

Escalation Not Working

Check time format:

# Correct
escalateAfter: 30m

# Incorrect
escalateAfter: "30 minutes"  # Won't parse

Check retry count:

ci-failed:
  retries: 2
  escalateAfter: 2  # Escalates after 2 failures

Next Steps

Custom Workflows

Create advanced automation with CI/CD integration

Multi-Project Setup

Manage reactions across multiple repositories