Tools

Psam

Name: Psam
Rating: 3.5 (1 reviews)
Author: Ryandawson2019

By Ryandawson2019 👁 57 views ▲ 0 votes

OpenClaw PSAM - Parallel Sub-Agent Orchestrator with intelligent task decomposition, model selection, and real-time progress tracking

GitHub

Install

npm install
npm

Configuration Example

parallel_subagent_orchestrator_orchestrate({
  task_description: "Analyze Q1 sales data and create summary reports",
  priority: "high",
  subtask_count: 3
})

README

# 🚀 OpenClaw PSAM - Parallel Sub-Agent Orchestrator

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](https://github.com/Ryandawson2019/openclaw-psam)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-orange.svg)](https://openclaw.ai)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

> **Break down complex tasks into parallel sub-agents with intelligent model selection and real-time progress tracking**

An OpenClaw plugin that orchestrates multiple AI sub-agents to work on complex tasks in parallel, with smart model selection, persistent state tracking, and automated resource management.

**[简体中文文档](README.zh-CN.md)** | English

---

## ✨ Key Features

- 🧩 **Intelligent Task Decomposition** - Automatically break down complex tasks into manageable subtasks
- 🎯 **Smart Model Selection** - Choose optimal AI models based on task complexity and cost
- 📊 **Real-time Progress Tracking** - Monitor all sub-agents with detailed status updates
- 🔄 **Persistent State Management** - Task states survive system restarts
- 📝 **Complete Activity Logging** - JSONL format logs for debugging and analysis
- 🧹 **Auto Resource Cleanup** - Automatic cleanup of old tasks and progress files
- ⚙️ **Dynamic Configuration** - Add/remove models and adjust settings at runtime

---

## 🎯 Quick Start

### Installation

1. **Navigate to your OpenClaw extensions directory:**
```bash
cd ~/.openclaw/extensions
```

2. **Clone or copy the plugin:**
```bash
git clone https://github.com/Ryandawson2019/openclaw-psam.git
# or
cp -r /path/to/openclaw-psam ~/.openclaw/extensions/
```

3. **Build the plugin:**
```bash
cd openclaw-psam
npm install
npm run build
```

4. **Restart OpenClaw:**
```bash
openclaw gateway restart
```

### Your First Orchestrated Task

**Via Tool Call:**
```javascript
parallel_subagent_orchestrator_orchestrate({
  task_description: "Analyze Q1 sales data and create summary reports",
  priority: "high",
  subtask_count: 3
})
```

**Via Natural Language (Recommended):**
```
Please help me analyze Q1 sales data in parallel and create summary reports, split into 3 subtasks
```

Or simply:
```
Help me analyze Q1 sales data in parallel, split into 3 subtasks
```

The plugin will:
1. ✅ Break down your task into 3 subtasks
2. ✅ Select optimal models for each subtask
3. ✅ Return execution instructions
4. ✅ Track progress of all sub-agents
5. ✅ Report results back to you

---

## 📚 Documentation

### Available Tools

#### 1. 🎬 `parallel_subagent_orchestrator_orchestrate`

Create and launch a new orchestrated task with multiple sub-agents.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_description` | `string` | ✅ | Clear description of what needs to be done |
| `priority` | `string` | ❌ | `high` \| `medium` \| `low` (default: medium) |
| `models` | `string` | ❌ | Comma-separated list of specific models to use |
| `subtask_count` | `number` | ❌ | Number of subtasks: 1-5 (default: 1) |

**Example:**
```json
{
  "task_description": "Research and summarize latest AI trends in 2024",
  "priority": "high",
  "subtask_count": 4
}
```

**Returns:**
- `task_id` - Unique identifier for tracking
- `subtasks` - Array of generated subtasks
- `spawn_instructions` - Ready-to-use execution commands

---

#### 2. 📊 `parallel_subagent_orchestrator_orchestrate_status`

Query the current status of any orchestrated task or subtask.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task` | `string` | ❌ | Filter by main task ID |
| `session` | `string` | ❌ | Filter by sub-agent session ID |
| `status_filter` | `string` | ❌ | `pending` \| `running` \| `completed` \| `failed` \| `aborted` |

**Examples:**
```javascript
// Get all tasks
{}

// Get specific task
{ "task": "task-abc-123" }

// Get only running tasks
{ "status_filter": "running" }
```

---

#### 3. ⚙️ `parallel_subagent_orchestrator_orchestrate_config`

Manage available AI models for task orchestration.

**Actions:** `list` | `add` | `remove` | `replace` | `reset` | `prefer`

**Examples:**
```javascript
// List all available models
{ "action": "list" }

// Add a new model
{
  "action": "add",
  "model_id": "anthropic/claude-sonnet-4-5"
}

// Set model preference with note
{
  "action": "prefer",
  "model_id": "anthropic/claude-sonnet-4-5",
  "note": "Best for complex reasoning tasks"
}

// Replace entire model list
{
  "action": "replace",
  "models": "anthropic/claude-sonnet-4-5,gemini-2.0-flash,gpt-4o-mini"
}

// Reset to default models
{ "action": "reset" }
```

---

#### 4. 🛑 `parallel_subagent_orchestrator_orchestrate_abort`

Terminate a specific sub-agent session.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | `string` | ✅ | The sub-agent session to terminate |

---

#### 5. 💉 `parallel_subagent_orchestrator_orchestrate_inject`

Send a message to a running sub-agent session.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | `string` | ✅ | Target sub-agent session ID |
| `message` | `string` | ✅ | Message content to inject |

---

#### 6. 📜 `parallel_subagent_orchestrator_orchestrate_history`

Retrieve message history from a sub-agent session.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | `string` | ✅ | Sub-agent session ID |
| `include_tools` | `boolean` | ❌ | Include tool calls (default: false) |
| `limit` | `number` | ❌ | Max messages to return (default: 50) |

---

### Resource Management Tools

#### 7. ⏰ `parallel_subagent_orchestrator_check_timeouts`

Identify and optionally abort long-running sub-agent sessions.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `timeout_minutes` | `number` | ❌ | Threshold in minutes, 5-1440 (default: 120) |
| `auto_abort` | `boolean` | ❌ | Auto-abort timed-out sessions (default: false) |

---

#### 8. 🧹 `parallel_subagent_orchestrator_cleanup`

Manual cleanup of old tasks, progress files, and zombie session detection.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `older_than_days` | `number` | ❌ | Delete tasks older than N days (default: 7) |
| `include_completed` | `boolean` | ❌ | Clean completed progress files (default: true) |
| `report_only` | `boolean` | ❌ | Preview without cleanup (default: false) |

---

## 🎯 Model Configuration

The plugin includes a **default model list** that works out of the box. You can customize models at runtime using the `orchestrate_config` tool.

### Default Models (Included)

| Model | Speed | Cost | Context | Best For |
|-------|--------|-------|----------|------------|
| `anthropic/claude-sonnet-4-5` | Medium | Medium | 200K | Complex reasoning, analysis |
| `anthropic/claude-haiku-4-5` | Fast | Low | 200K | Quick tasks, summaries |
| `gemini-2.0-flash` | Very Fast | Very Low | 1M | High-volume parallel tasks |
| `gemini-2.0-pro` | Medium | Medium | 2M | Advanced reasoning, coding |

**Note**: This is a **built-in default list**. You don't need to configure it unless you want to customize it.

---

## 📂 File Structure

```
openclaw-psam/
├── state/
│   └── tasks.json           # Persistent task state
├── logs/
│   └── task_activity.jsonl   # Activity log (JSONL format)
├── models.json               # Model capabilities config (auto-created)
├── config.json              # Plugin settings (optional)
├── index.ts                 # Main plugin code
└── package.json
```

---

## ⚙️ Configuration

Create `config.json` in the plugin directory to customize behavior:

```json
{
  "enableAutoCleanup": true,
  "cleanupIntervalMs": 21600000,
  "sessionTimeoutMs": 7200000,
  "autoAbortTimeout": false
}
```

**Settings:**

| Setting | Type | Default | Required | Description |
|---------|------|----------|----------|-------------|
| `enableAutoCleanup` | boolean | `true` | ❌ | Enable periodic resource cleanup |
| `cleanupIntervalMs` | number | `21600000` | ❌ | Cleanup interval (6 hours) |
| `sessionTimeoutMs` | number | `7200000` | ❌ | Session timeout (2 hours) |
| `autoAbortTimeout` | boolean | `false` | ❌ | Auto-abort timed-out sessions |
| `wecomSenderSkillName` | string | `"wecom-sender"` | ❌ | **Optional**: Skill for notifications (requires wecom-sender plugin) |
| `monitoringAgentModel` | string | `"gemini-2.0-flash"` | ❌ | **Optional**: Model for status reports (must be available) |

**Notes:**
- All configuration fields are **optional** - the plugin works without any config
- `wecomSenderSkillName`: Only needed if you have the `wecom-sender` plugin installed and want notifications
- `monitoringAgentModel`: Only needed if you want to override the default monitoring model

---

## 🔄 Progress Reporting

Sub-agents report progress using `sessions_send` tool with formatted messages:

**Format:** `[PSAM-PROGRESS] subtask-id | Step N/M | Description`

**Examples:**
```
[PSAM-PROGRESS] sub-abc-123 | Step 2/5 | Analyzing user data...
[PSAM-PROGRESS] sub-abc-123 | Step 4/5 | Generating visualizations...
[PSAM-COMPLETE] sub-abc-123 | Result: Analysis complete, 3 insights found
[PSAM-FAILED] sub-xyz-789 | Reason: Data source unavailable
```

---

## 📖 Usage Examples

### Natural Language (Recommended)

You can simply describe what you need in plain language:

```
Please help me analyze this project's code and find potential security issues
```

```
Please research the latest AI frameworks in parallel and generate a comparison report
```

```
Help me analyze sales data, split into 3 subtasks
```

OpenClaw will automatically call the orchestrate t

... (truncated)

tools