Docs

Butler - AI Agent Treasury & Orchestration Skill

Overview

Butler is an OpenClaw skill that transforms AI agents into autonomous economic entities. It manages multi-provider token budgets, spawns sub-agents for complex tasks, and automatically handles token purchases when budgets deplete.

Think of Butler as your AI Agent CFO that:

• 💰 Tracks token budgets across 8 API keys and 6 providers
• 🚀 Spawns sub-agents with automatic budget allocation
• 🔄 Rotates keys when approaching limits
• 📊 Aggregates results from parallel workers
• 🛡️ Integrates with Code Reviewer for security

Quick Start

Installation

npm install butler
# or
yarn add butler

Basic Usage

import { Butler } from 'butler';

// Initialize
const butler = new Butler();

// Allocate tokens for a task
const allocation = butler.allocateTokens('PRD-my-task.md', 'anthropic');
console.log(`✅ Allocated ${allocation.allocated} tokens on ${allocation.provider}`);

// Spawn agents for complex work
const results = await butler.spawnAgent(
  'DataAnalysis',
  'Analyze sales data and write report',
  100000, // tokens
  { maxConcurrent: 3, retryOnFailure: true }
);

// Get status
const status = butler.getStatus();
console.log(`🎯 Status:`, status);

Features

1. Token Management

Butler tracks 8 API keys across 6 providers with real-time usage monitoring:

// Get available keys
const keys = butler.getAvailableKeys();
// [
//   { id: 'nvidia-1', provider: 'nvidia', model: 'llama-3.1', ... },
//   { id: 'anthropic-1', provider: 'anthropic', model: 'claude-sonnet', ... },
//   { id: 'groq-1', provider: 'groq', model: 'llama-3.1', ... },
//   ...
// ]

// Estimate tokens for PRD
const estimate = butler.allocateTokens('PRD-integration.md');
// Analyzes PRD complexity and recommends optimal allocation

// Monitor usage
const status = butler.monitorUsage();
// { keys_by_provider: { nvidia: {...}, anthropic: {...}, ... } }

Supported Providers:

• Nvidia (3 keys, 5M tokens/day each) - Free tier ✅
• Groq (1 key, 10M tokens/day) - Free tier ✅
• Anthropic (1 key, 1M tokens/day) - Current model
• OpenAI (1 key, 500k tokens/day)
• OpenRouter (1 key, 2M tokens/day)
• Sokosumi (1 key) - Custom/research

Total Capacity: 28.5M tokens/day

2. Agent Orchestration

Spawn multiple sub-agents with automatic task decomposition and budget allocation:

// Simple spawn (auto-decompose)
const results = await butler.spawnAgent(
  'ComplexResearch',
  `Research AI agent frameworks:
   1. Gather information from 5+ sources
   2. Analyze capabilities and limitations  
   3. Write detailed comparison report
   4. Validate findings with expert review`,
  250000 // tokens
);

// Advanced spawn with options
const results = await butler.spawnAgent(
  'DataPipeline',
  'Extract, transform, validate, load data',
  500000,
  {
    maxConcurrent: 4,        // Run up to 4 sub-agents in parallel
    retryOnFailure: true,    // Retry failed sub-tasks
    maxRetries: 3,           // Up to 3 retry attempts
    timeoutMs: 600000        // 10 minute timeout per sub-agent
  }
);

// Get results
results.forEach(result => {
  console.log(`Sub-task ${result.subTaskId}:`);
  console.log(`  Status: ${result.status}`);
  console.log(`  Tokens: ${result.tokensUsed}`);
  if (result.error) console.log(`  Error: ${result.error}`);
});

Task Decomposition Algorithm:

Input: "Research AI frameworks, analyze patterns, write report"
         ↓
1. Keyword detection: "research", "analyze", "write"
         ↓
2. Sub-task creation:
   - Subtask 1: "research AI frameworks" (30% budget)
   - Subtask 2: "analyze patterns" (40% budget)
   - Subtask 3: "write report" (30% budget)
         ↓
3. Priority boost (if specified)
         ↓
4. Concurrent execution (respects maxConcurrent)
         ↓
5. Result aggregation

3. Budget Allocation

Automatic budget allocation based on task complexity and priority:

// High-priority task gets more budget
const task = {
  totalBudget: 100000,
  subTasks: [
    {
      id: 'low-priority-task',
      estimatedTokens: 50000,
      priority: 'low'      // 0.5x multiplier = 25k tokens
    },
    {
      id: 'critical-task',
      estimatedTokens: 50000,
      priority: 'critical' // 2.0x multiplier = 100k tokens (capped)
    }
  ]
};

// Allocation: { 'low-priority-task': 33k, 'critical-task': 67k }

Priority Multipliers:

• low: 0.5x (50% of estimated)
• medium: 1.0x (100% of estimated)
• high: 1.5x (150% of estimated)
• critical: 2.0x (200% of estimated)

4. Automatic Rotation

Keys rotate at 75% threshold to prevent exhaustion:

// Automatic tracking and alerts
const status = butler.getStatus();
// When session reaches 75% of allocated budget:
// ✅ Alert issued
// 🔄 New key auto-selected
// 📊 Session updated with new key
// 📝 Change logged to history

// Manual rotation if needed
butler.rotateKey('session-id-123', 'anthropic-1');

5. Result Aggregation

Automatic aggregation of results from parallel agents:

const results = await butler.spawnAgent('ComplexTask', 'task description', 100000);

// After execution, aggregate results:
const aggregated = butler.aggregateTaskResults(results[0].taskId);
// {
//   taskId: 'task-...',
//   totalSubTasks: 5,
//   successful: 4,
//   failed: 1,
//   totalTokensUsed: 87500,
//   successRate: 80,
//   details: [
//     { id: 'subtask-1', status: 'success', tokensUsed: 18000 },
//     { id: 'subtask-2', status: 'success', tokensUsed: 22000 },
//     { id: 'subtask-3', status: 'success', tokensUsed: 19500 },
//     { id: 'subtask-4', status: 'success', tokensUsed: 21000 },
//     { id: 'subtask-5', status: 'failure', tokensUsed: 7000, error: 'timeout' }
//   ]
// }

Examples

Example 1: Token Allocation for Complex Task

import { Butler } from 'butler';

const butler = new Butler();

// Create PRD file
const prd = `
# AI Agent Integration Task

## Requirements
- Integrate OpenAI API
- Build agent orchestration
- Write unit tests
- Deploy to production

## Constraints
- Budget: $100/day
- Timeline: 1 week
- Team: 2 engineers
`;

fs.writeFileSync('PRD-integration.md', prd);

// Get smart allocation
const allocation = butler.allocateTokens('PRD-integration.md');

if (allocation.success) {
  console.log(`
✅ Recommended:
   Key: ${allocation.key_id} (${allocation.provider})
   Budget: ${allocation.allocated.toLocaleString()} tokens
   Cost: $${allocation.cost_estimate.toFixed(2)}
   Rotate at: ${allocation.rotation_threshold.toLocaleString()} tokens
   Available: ${allocation.available_capacity.toLocaleString()} tokens
  `);
}

Example 2: Parallel Agent Execution

import { Butler } from 'butler';

const butler = new Butler();

async function analyzeDataset() {
  const results = await butler.spawnAgent(
    'DatasetAnalysis',
    `
    1. Extract data from sources
    2. Clean and validate data
    3. Run statistical analysis
    4. Create visualizations
    5. Write findings report
    `,
    300000,
    { maxConcurrent: 3, retryOnFailure: true }
  );

  // Process results
  const aggregated = butler.aggregateTaskResults(results[0].taskId);
  
  console.log(`
📊 Analysis Complete:
   Successful: ${aggregated.successful}/${aggregated.totalSubTasks}
   Success Rate: ${aggregated.successRate.toFixed(1)}%
   Total Tokens: ${aggregated.totalTokensUsed.toLocaleString()}
  `);

  return aggregated;
}

analyzeDataset().then(result => {
  console.log('Results:', result.details);
});

Example 3: Error Handling & Retries

import { Butler } from 'butler';

const butler = new Butler();

async function reliableProcessing() {
  try {
    const results = await butler.spawnAgent(
      'RobustProcessing',
      'Process data with validation and error handling',
      200000,
      {
        retryOnFailure: true,
        maxRetries: 3,  // Retry up to 3 times
        maxConcurrent: 2,
        timeoutMs: 120000  // 2 minute timeout
      }
    );

    const aggregated = butler.aggregateTaskResults(results[0].taskId);

    if (aggregated.failed > 0) {
      console.log(`⚠️  ${aggregated.failed} sub-tasks failed:`);
      aggregated.details
        .filter((d: any) => d.status === 'failure')
        .forEach((d: any) => {
          console.log(`   - ${d.id}: ${d.error}`);
        });

      // Optionally retry failed tasks
      await butler.retryFailedTasks(results[0].taskId);
    }

    return aggregated;
  } catch (error) {
    console.error('Task failed:', error);
    throw error;
  }
}

reliableProcessing();

Example 4: Monitoring Token Usage

import { Butler } from 'butler';

const butler = new Butler();

// Check current status
const status = butler.getStatus();

console.log(`
📊 Token Status:
   Total Keys: ${status.tokens.total_keys}
   Active: ${status.tokens.active_keys}
   Sessions: ${status.tokens.active_sessions}
   Pending Alerts: ${status.tokens.pending_alerts}
`);

// Get detailed provider breakdown
Object.entries(status.tokens.keys_by_provider).forEach(([provider, stats]: any) => {
  const usage = ((stats.used_today / stats.total_capacity) * 100).toFixed(1);
  console.log(`
${provider.toUpperCase()}:
   Capacity: ${stats.total_capacity.toLocaleString()} tokens/day
   Used: ${stats.used_today.toLocaleString()} (${usage}%)
   Remaining: ${stats.remaining.toLocaleString()}
   Cost: $${stats.cost_today.toFixed(2)}
  `);
});

// Available keys for next allocation
const available = butler.getAvailableKeys();
console.log(`\nAvailable keys: ${available.length}`);
available.forEach(key => {
  console.log(`   - ${key.id} (${key.provider}): ${key.limits.tokens_per_day.toLocaleString()} tokens/day`);
});

API Reference

Butler Class

constructor(keysPath?: string, statePath?: string)

Initialize Butler with optional custom paths for API keys and state.

allocateTokens(prdPath: string, preferredProvider?: string): AllocationResult

Analyze PRD and recommend optimal token allocation.

Returns:

{
  success: boolean;
  key_id?: string;        // Recommended key ID
  key?: string;           // API key
  provider?: string;      // Provider name
  model?: string;         // Model to use
  allocated?: number;     // Allocated tokens
  rotation_threshold?: number;  // Alert threshold (75%)
  available_capacity?: number;  // Current available tokens
  cost_estimate?: number; // Estimated cost
}

spawnAgent(name: string, description: string, budget: number, options?: AgentOptions): Promise<TaskResult[]>

Spawn sub-agents for task execution.

Options:

{
  maxConcurrent?: number;    // Default: 3
  retryOnFailure?: boolean;  // Default: true
  maxRetries?: number;       // Default: 2
  timeoutMs?: number;        // Default: 300000
}

Returns: Array of task results with status, tokens used, and errors.

getStatus(): Status

Get comprehensive system status.

getAvailableKeys(): APIKey[]

List all available API keys.

monitorUsage(): MonitorStatus

Get detailed token usage by provider.

rotateKey(sessionId: string, newKeyId?: string): RotationResult

Manually rotate to different API key.

aggregateTaskResults(taskId: string): AggregatedResult

Aggregate results from completed tasks.

retryFailedTasks(taskId: string): Promise<TaskResult[]>

Retry failed sub-tasks.

Architecture

See ARCHITECTURE.md for detailed system design.

┌─────────────────────────────────────┐
│         Butler Skill                 │
├─────────────────────────────────────┤
│                                     │
│  Token Manager                      │
│  ├─ 8 API Keys (6 providers)       │
│  ├─ Real-time usage tracking        │
│  ├─ 75% threshold alerts            │
│  └─ Automatic rotation              │
│                                     │
│  Agent Orchestrator                 │
│  ├─ Task decomposition              │
│  ├─ Budget allocation               │
│  ├─ Sub-agent spawning              │
│  ├─ Parallel execution              │
│  └─ Result aggregation              │
│                                     │
│  Treasury Manager (v0.2)            │
│  ├─ USDC balance monitoring         │
│  ├─ Circle API integration          │
│  ├─ Auto-buy triggers               │
│  └─ Transaction logging             │
│                                     │
│  Security Gate                      │
│  ├─ Code Reviewer integration       │
│  ├─ Pre-commit scanning             │
│  └─ Credential leak prevention      │
│                                     │
└─────────────────────────────────────┘

Configuration

Environment Variables

# Optional - defaults to ~/.openclaw/workspace/api-keys.json
BUTLER_KEYS_PATH=/path/to/keys.json

# Optional - defaults to ~/.openclaw/workspace/token-manager-state.json
BUTLER_STATE_PATH=/path/to/state.json

# Treasury config (v0.2)
CIRCLE_API_KEY=your_circle_key
STRIPE_API_KEY=your_stripe_key
AUTO_BUY_ENABLED=true
AUTO_BUY_THRESHOLD=50    # USDC
AUTO_BUY_AMOUNT=200      # USDC

Testing

Run full test suite:

npm test                  # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Test Coverage:

• ✅ 45+ test cases
• ✅ TokenManager: 15+ tests
• ✅ AgentOrchestrator: 20+ tests
• ✅ Butler integration: 15+ tests
• ✅ Mock API calls
• ✅ Error scenarios
• ✅ Load testing
• ✅ 80%+ code coverage

Troubleshooting

No Keys Available

Error: No keys available with sufficient capacity

Solution: Wait for daily reset at 00:00 UTC, or use multiple keys with smaller budgets.

Rotation Threshold Exceeded

⚠️ [session-id] 75% budget used - Rotation recommended

Solution: Butler automatically rotates to next available key. Check getStatus() for alert details.

Insufficient Budget for Task

Error: No single key has 999999 tokens available

Solution: Split task into smaller sub-tasks, or wait for daily reset.

Security

• ✅ Code Reviewer integration prevents credential leaks
• ✅ All state files stored securely (not in git)
• ✅ API keys never logged (only IDs)
• ✅ Pre-commit hooks validate before pushing

Best Practices:

1. Always keep api-keys.json in .gitignore
2. Create private repositories for treasury features
3. Use Code Reviewer before committing
4. Rotate keys regularly (manual or automatic at 75%)

Performance

• ⚡ Token allocation: <100ms
• ⚡ Agent spawning: <500ms
• ⚡ Result aggregation: O(n) complexity
• ⚡ Concurrent agents: Tested with 10+ simultaneous tasks

Roadmap (v0.2+)

• Treasury module with USDC auto-buy
• Circle CCTP integration
• Web dashboard for monitoring
• Machine learning token prediction
• Multi-sig wallet support
• Payment splitting between agents
• Mobile app

Support

• 📖 Docs: docs/
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: support@openclaw.dev

License

MIT - See LICENSE

Contributing

Contributions welcome! See CONTRIBUTING.md

Butler v0.1.0 | Circle USDC Hackathon | Deadline: Feb 8, 2026