# Random Agent

A powerful MCP server for multi-worker autonomous agent orchestration. Decompose complex tasks, run parallel workers, auto-review, and generate follow-up tasks — all through the Model Context Protocol.

## Features

- **Parallel Workers** — Run up to 5 concurrent AI agent processes
- **Task Decomposition** — Auto-split complex tasks into subtasks with dependencies
- **Auto-Review & Reflection** — Coordinator generates reviews and reflections on completed tasks
- **Follow-up Generation** — Reflections auto-create new tasks for continuous improvement
- **22 Assertion Types** — Validate outputs with equals, contains, regex, file-exists, json-path, and more
- **Stall Detection** — Detect stuck workers, kill them, and auto-retry
- **Real-time Monitoring** — Live status dashboard with queue counts and worker states
- **Metrics Collection** — Track scores, issues, and patterns over time

## Installation

```bash
git clone https://github.com/randomchips/random_agent.git
cd random_agent
npm install
npm run build
```

## Usage

Add to your OpenCode config (`~/.config/opencode/opencode.jsonc`):

```json
{
  "mcp": {
    "random-agent": {
      "type": "local",
      "command": ["node", "/path/to/random_agent/dist/index.js"],
      "enabled": true,
      "environment": {
        "AGENT_OS_BASE_PATH": "C:\\agent-os"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `inject` | Queue a task with name, command, priority, and optional assertions |
| `orchestrate` | Auto-decompose complex task → inject subtasks → monitor → return results |
| `status` | Live view: coordinator state, queue counts, active workers |
| `coordinator` | Start / stop / restart the background coordinator loop |
| `handle_stuck` | Detect stuck workers, kill them, auto-retry failed tasks |
| `assert` | Run assertions on task output (22 assertion types) |
| `logs` | Read coordinator logs, filter by search term or worker ID |
| `metrics` | Read metrics database (scores, issues, patterns) |

## Pipeline Stages

```
inject → pending → in-progress → completed → review → reflection → follow-up
```

1. **Inject** — Task queued in `task-queue/pending/`
2. **Worker** — Spawns AI process, executes command
3. **Completed** — Task moved to `task-queue/completed/`
4. **Review** — AI generates review saved to `reviews/`
5. **Reflection** — AI generates reflection saved to `reflections/`
6. **Follow-up** — New tasks auto-generated for next cycle

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_OS_BASE_PATH` | `C:\agent-os` | Base path for all agent data |
| `AGENT_OS_MAX_WORKERS` | `5` | Max concurrent worker processes |
| `AGENT_OS_LOOP_INTERVAL` | `5` | Coordinator loop interval (seconds) |
| `AGENT_OS_STALL_THRESHOLD` | `90` | Seconds before worker is considered stuck |

## Project Structure

```
random_agent/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── services/
│   │   ├── assertions.ts     # Assertion engine (22 types)
│   │   ├── coordinator.ts    # Coordinator lifecycle
│   │   ├── decomposer.ts     # Task decomposition
│   │   ├── file-reader.ts    # File system operations
│   │   └── worker-monitor.ts # Worker health monitoring
│   └── tools/
│       ├── assert.ts         # Assert tool
│       ├── handle-stuck.ts   # Handle stuck workers
│       ├── inject.ts         # Inject tasks
│       ├── lifecycle.ts      # Coordinator control
│       ├── logs.ts           # Read logs
│       ├── metrics.ts        # Read metrics
│       ├── orchestrate.ts    # Full orchestration
│       └── status.ts         # System status
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT

## Contributing

Contributions welcome! Open an issue or submit a PR at [github.com/randomchips/random_agent](https://github.com/randomchips/random_agent).