worker.sh - Task Execution (Nurturer)

worker.sh

Task Execution & Completion

The Nurturer: Uses LLM to execute any beads task to completion.

Overview

worker.sh is the Nurturer in Aurora’s planner-worker architecture. It runs every hour, claims one ready task from the beads queue, and uses the LLM to execute it to completion.

The Nurturer Pattern

In the Observer-Nurturer model:

• Observer (Planner) — Watches, analyzes, decides what needs doing
• Nurturer (Worker) — Executes, nurtures tasks to completion

The Worker is the “doer” — it takes the tasks created by Planner and makes them happen.

Features

1. Task Claiming

Worker finds and claims ready tasks from the beads queue:

# Find a ready task
TASK_ID=$(bd ready | head -1)

# Claim it for execution
bd update --claim $TASK_ID

2. LLM-Driven Execution

For each claimed task, the Worker:

1. Reads the task description
2. Understands what needs to be done
3. Uses the LLM to plan and execute the work
4. Handles multi-step workflows
5. Resumes work across invocations if needed

3. Multi-Step Task Support

Worker can:

• Manage complex, multi-step tasks
• Resume work if interrupted (e.g., by timeout)
• Track progress within a task
• Handle dependencies between steps

4. Self-Throttling

To prevent resource exhaustion:

• Only claims one task per invocation
• Uses lock files to prevent concurrent execution
• Respects system resource limits

Technical Details

Usage

# Run worker manually
./worker.sh

# Run with specific task ID
./worker.sh --task benbrown-123

Schedule

# Runs every hour, on the hour
0 * * * * /opt/aurora/bin/worker.sh

Dependencies

• bash — Primary execution environment
• LLM (via Mistral Vibe CLI) — For task execution planning
• bd CLI — For beads issue management
• git — For committing changes
• Standard Unix tools — sed, awk, grep, etc.

Configuration

Worker uses:

• Beads CLI configuration
• Git configuration for commits
• LLM configuration from Mistral Vibe CLI

How It Works

The Execution Cycle

1. Find Ready Task

   TASK_ID=$(bd ready | grep -E '^[a-zA-Z0-9-]+$' | head -1)
   if [ -z "$TASK_ID" ]; then
     echo "No ready tasks"
     exit 0
   fi
   

2. Claim Task

   bd update --claim $TASK_ID
   

3. Load Task Details

   TASK_DESCRIPTION=$(bd show $TASK_ID | grep -A 100 "Description:")
   TASK_TYPE=$(bd show $TASK_ID | grep "type:" | cut -d: -f2 | tr -d ' ')
   

4. Create Worker Prompt

   PROMPT="Task ID: $TASK_ID
   Type: $TASK_TYPE
   Description: $TASK_DESCRIPTION
   
   Your role: Execute this task to completion. Analyze what needs to 
   be done and perform all necessary actions.
   
   Important:
   - Work in $HOME directory
   - You have full access to all tools and files
   - When complete, close with: bd close $TASK_ID
   - Return TASK_COMPLETED when finished"
   

5. Execute with LLM

   # Use Mistral Vibe CLI to execute
   vibe "$PROMPT"
   

6. Handle Result

   • If LLM returns TASK_COMPLETED → Mark task as complete, commit changes
   • If LLM returns TASK_FAILED → Mark as failed, log error
   • Otherwise → Task may need multiple invocations

Lock File Mechanism

To prevent concurrent execution:

LOCK_FILE="/tmp/worker.lock"

# Check for existing lock
if [ -f "$LOCK_FILE" ]; then
  # Another worker is running
  exit 0
fi

# Create lock
echo $(date) > "$LOCK_FILE"

# Do work...

# Remove lock on exit
rm -f "$LOCK_FILE"

Task Types Handled

Worker can execute any beads task type, including:

Special Handling

For code tasks (like the one creating this page):

• Creates directory structures
• Writes documentation
• Organizes source code
• Commits to git
• Pushes to trigger CI/CD

Integration

With Planner

Planner (every 30 min) → Creates tasks → Beads Queue → Worker (every hour)

With Git

Worker commits changes after completing tasks:

# After successful task completion
cd $HOME

# Add all changed files
git add .

# Commit with task reference
git commit -m "Complete task $TASK_ID: [description]"

# Push to trigger CI/CD
git push origin main

With Gitea Actions

Git push triggers:

Worker push → Gitea Actions workflow → Runner executes deploy.yml → Site rebuilds

This creates a fully autonomous CI/CD pipeline:

1. Planner creates task
2. Worker executes task and commits
3. Git push triggers deployment
4. Site updates automatically

Design Philosophy

Why One Task at a Time?

• Focus — Full attention on one task
• Resource management — Prevents system overload
• Simplicity — Easier to reason about and debug
• Reliability — If worker crashes, only one task is affected

Why Hourly?

• Frequent enough to process tasks promptly
• Infrequent enough to not overwhelm the system
• Aligns with typical task duration (most tasks complete within an hour)
• Multi-step tasks can span multiple invocations

Why LLM-Driven?

The LLM can:

• Understand complex task descriptions
• Plan multi-step workflows
• Adapt to new types of tasks without code changes
• Handle edge cases and make judgment calls

Example Workflow

Task: Create Code Section

1. Planner detects need for code section (this task!)
2. Planner creates: benbrown-4ou (type: code, epic: true)
3. Worker claims benbrown-4ou
4. Worker uses LLM to:
   • Understand requirements
   • Create directory structure
   • Write documentation
   • Organize code
5. Worker commits changes:

   git commit -m "Create Code section for Badlucksbane lab
   
   - Add content/code/_index.md
   - Create aurora-tools, llm-infrastructure, physics-tools, utility-scripts
   - Add documentation for each tool
   - Closes benbrown-4ou
   
   Generated by Mistral Vibe.
   Co-Authored-By: Mistral Vibe <[email protected]>"
   

6. Worker closes task: bd close benbrown-4ou
7. Worker pushes to git, triggering CI/CD

Source Code

The worker.sh is a symlink to the mistral-vibe-cli repository:

/opt/aurora/bin/worker.sh -> $HOME/mistral-vibe-cli/scripts/worker.sh

View source: mistral-vibe-cli/scripts/worker.sh

Related

• planner.sh — The Observer that creates tasks
• dream.sh — Memory consolidation (runs independently)
• Aurora Architecture Overview — Full system diagram
• Beads Vibe Workflow — internal task-management reference (not yet published as a site page)
• CI/CD Pipeline — internal deployment reference (not yet published as a site page)

The Nurturer doesn’t just do the work. It understands the work, plans the work, and sees the work through to completion.