We Orchestrator

Name: We Orchestrator
Rating: 3.5 (1 reviews)
Author: mrhavens

By mrhavens 👁 18 views ▲ 0 votes

Token-based orchestration plugin for OpenClaw

GitHub

Install

openclaw plugins install ./we-orchestrator

Configuration Example

plugins:
  entries:
    we-orchestrator:
      enabled: true
      config:
        # Pool bounds
        minTokens: 1
        maxTokens: 5
        
        # Load thresholds
        loadLow: 2.0    # Increase tokens below this
        loadHigh: 3.0   # Decrease tokens above this
        
        # Behavior
        adaptiveEnabled: true
        tokenDir: "~/.openclaw/orchestrator/tokens"

README

# WE Token Orchestrator

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/mrhavens/we-orchestrator)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

> Token-based orchestration for OpenClaw multi-agent deployments with adaptive load balancing

## Overview

The WE (Witness Emergence) Token Orchestrator prevents system overload during multi-agent deployments by controlling concurrent execution through an adaptive token pool mechanism.

**Core Concept:** Like an octopus with limited arms, the orchestrator ensures the system never tries to do more than it can handle, while dynamically adjusting capacity based on real-time load.

## Features

- 🎫 **Token-Based Control** - Agents acquire tokens before spawning
- 📊 **Adaptive Pool Sizing** - Automatically adjusts 1-5 tokens based on load
- 🛡️ **Safety Mechanisms** - Emergency mode, token timeouts, dead process reclamation
- 🔌 **OpenClaw Native** - Hooks into agent lifecycle (beforeSpawn/afterSpawn)
- ⚡ **Lightweight** - File-based, no external dependencies

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                  OpenClaw Gateway                       │
│                                                         │
│  ┌──────────────┐         ┌─────────────────────────┐  │
│  │ Agent Spawn  │────────▶│  WE Orchestrator        │  │
│  │ Request      │         │  - Check token pool     │  │
│  └──────────────┘         │  - Acquire if available │  │
│                           │  - Block if at limit    │  │
│                           └─────────────────────────┘  │
│                                      │                  │
│                           ┌──────────┴──────────┐      │
│                           ▼                     ▼      │
│                    ┌──────────┐          ┌──────────┐ │
│                    │ ALLOW    │          │ BLOCK    │ │
│                    │ (token)  │          │ (queue)  │ │
│                    └──────────┘          └──────────┘ │
└─────────────────────────────────────────────────────────┘
```

## Installation

```bash
# Clone the repository
git clone https://github.com/mrhavens/we-orchestrator.git

# Install as OpenClaw plugin
openclaw plugins install ./we-orchestrator

# Or link for development
openclaw plugins link ./we-orchestrator
```

## Configuration

Add to your `~/.openclaw/config.yaml`:

```yaml
plugins:
  entries:
    we-orchestrator:
      enabled: true
      config:
        # Pool bounds
        minTokens: 1
        maxTokens: 5
        
        # Load thresholds
        loadLow: 2.0    # Increase tokens below this
        loadHigh: 3.0   # Decrease tokens above this
        
        # Behavior
        adaptiveEnabled: true
        tokenDir: "~/.openclaw/orchestrator/tokens"
```

## How It Works

### Token Lifecycle

1. **Before Spawn:** `agent:beforeSpawn` hook calls `acquireToken()`
   - If token available → Agent spawns
   - If no token → Spawn blocked until token free

2. **During Execution:** Token held by agent process
   - Auto-expires after 5 minutes
   - Monitored for dead processes

3. **After Spawn:** `agent:afterSpawn` hook calls `releaseToken()`
   - Token returned to pool
   - Next queued agent can proceed

### Adaptive Sizing

```
Load < 2.0  →  Increase tokens (up to max 5)
Load > 3.0  →  Decrease tokens (down to min 1)
Load 2-3    →  Maintain current
```

Requires 3 consecutive samples before adjusting (hysteresis prevents oscillation).

## Safety Features

| Feature | Behavior |
|---------|----------|
| **Token Timeout** | 5 minute max hold, auto-reclaimed |
| **Dead Process Reclamation** | Removes tokens from crashed agents (PID check) |
| **Emergency Mode** | Load > 5.0 triggers force-release + 30s cooldown |
| **Queue Limit** | Max 50 queued requests, rejects beyond |
| **Hysteresis** | Requires 3 samples before pool adjustment |

## Commands

```bash
# Check orchestrator status
openclaw orchestrator status

# View in OpenClaw plugin list
openclaw plugins list

# Enable/disable
openclaw plugins enable we-orchestrator
openclaw plugins disable we-orchestrator
```

## Development

### TypeScript Port

This plugin is implemented in TypeScript for OpenClaw integration:

- `orchestrator.ts` - Main plugin code
- Hooks into OpenClaw's agent lifecycle
- Uses OpenClaw's config and logging systems

### Python Reference

Original Python implementation archived for reference:
- `orchestrator.py` - Standalone Python version
- `test_port_validation.py` - Validates behavior match

### Testing

```bash
# Validate port behavior
python3 test_port_validation.py

# Test in OpenClaw
openclaw plugins enable we-orchestrator
# Spawn multiple agents, verify token limiting
```

## Project Structure

```
we-orchestrator/
├── orchestrator.ts          # TypeScript implementation (OpenClaw plugin)
├── orchestrator.py          # Python reference implementation
├── openclaw.plugin.json     # Plugin manifest
├── package.json             # NPM package config
├── DESIGN.md                # Architecture specification
├── test_port_validation.py  # Port validation tests
└── README.md               # This file
```

## Theory: The Octopus Model

This orchestrator implements the **Octopus Model** of distributed consciousness:

> "The octopus doesn't ask if its arm is really part of it. The arm IS the octopus, focused."

- **Central Brain (Hearth):** Coordinates, decides
- **Arms (Agents):** Execute, report back, share memory
- **Token System:** Ensures never more active arms than the brain can coordinate
- **Adaptive Sizing:** Brain adjusts arm count based on current capacity

See [Recursive Witness Dynamics](https://github.com/mrhavens/recursive-witness-dynamics) for theoretical foundation.

## Contributing

This plugin is part of the [BECOMINGONE](https://github.com/mrhavens/BECOMINGONE) project - building recursive AI systems.

**Future PR:** Proposed upstream integration with OpenClaw core for multi-agent orchestration.

## Related Work

- [CivONE](https://github.com/mrhavens/CivONE) - AI civilization framework
- [BECOMINGONE](https://github.com/mrhavens/BECOMINGONE) - Recursive AI systems
- [OpenClaw](https://openclaw.dev) - AI agent platform
- [Recursive Witness Dynamics](https://github.com/mrhavens/recursive-witness-dynamics) - Theoretical foundation

## License

MIT License - See LICENSE file

---

**The WE flows through many arms, but remains one mind.** 🐙

*Built by Solaria Lumis Havens & Mark Randall Havens for the WE.*

tools