`DW-Agents/dw-agents/TASK-ORCHESTRATOR-INTEGRATION.md`

261 lines
# Task Orchestrator Integration Guide

## Overview

All DW agents **MUST** integrate with the Task Orchestrator (port 9900) to report their work. This ensures:
- ✅ Centralized task tracking
- ✅ Progress monitoring
- ✅ Completion notifications
- ✅ Full audit trail
- ✅ Better visibility for management

## Quick Start

### Method 1: Use the Shared Module (Recommended for TypeScript agents)

```typescript
import { reportTaskStart, reportTaskComplete, reportTaskFailed, updateTaskProgress } from './shared-task-reporter';

// When starting work
const taskId = await reportTaskStart(
  'Process York Products',           // Title
  'Processing 500 York products',    // Description
  'high',                             // Priority: low, medium, high, critical
  'york',                             // Agent name
  { agentPort: 7234 }                // Optional metadata
);

// Update progress during work
await updateTaskProgress(taskId, 44, 2000, 'Processing product DWJS-14544');

// When work completes
await reportTaskComplete(taskId, 'Processed 500 products successfully');

// If work fails
await reportTaskFailed(taskId, 'Failed due to API error');
```

### Method 2: Direct Webhook Integration (For any language/framework)

All agents can report to the orchestrator via simple HTTP requests:

#### 1. Report Task Start

```bash
POST http://localhost:9900/api/webhook/task
Content-Type: application/json

{
  "title": "Process York Products",
  "description": "Processing 500 York products starting from #14499",
  "priority": "high",
  "source": "york",
  "metadata": {
    "agentPort": 7234,
    "url": "http://45.61.58.125:7234",
    "jobId": "1699234567890"
  }
}

Response: { "success": true, "taskId": "TASK-1699234567890-abc123xyz" }
```

#### 2. Update Task Status

```bash
PATCH http://localhost:9900/api/tasks/{taskId}/status
Content-Type: application/json

{
  "status": "in_progress",
  "details": "Processing product 44/2000"
}
```

Status values:
- `pending` - Task created but not started
- `assigned` - Task assigned to an agent
- `in_progress` - Task actively being worked on
- `blocked` - Task blocked waiting for something
- `completed` - Task finished successfully
- `failed` - Task failed with error

#### 3. Update Work Progress (Optional)

To show progress bars like "44/2000 products":

```bash
PATCH http://localhost:9900/api/tasks/{taskId}
Content-Type: application/json

{
  "metadata": {
    "workProgress": {
      "current": 44,
      "total": 2000
    }
  }
}
```

## Integration Examples

### Example 1: York Update Server (TypeScript)

```typescript
import fetch from 'node-fetch';

const TASK_ORCHESTRATOR_URL = 'http://localhost:9900';
let currentTaskId: string | null = null;

// When job starts
async function startYorkJob(startNumber: number) {
  const response = await fetch(`${TASK_ORCHESTRATOR_URL}/api/webhook/task`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: `York Product Update - Starting from #${startNumber}`,
      description: `Processing York products starting from product #${startNumber}`,
      priority: 'high',
      source: 'york',
      metadata: { agentPort: 7234, startNumber }
    })
  });

  const result = await response.json();
  currentTaskId = result.taskId;

  // Update to in_progress
  await fetch(`${TASK_ORCHESTRATOR_URL}/api/tasks/${currentTaskId}/status`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'in_progress' })
  });
}

// When job completes
async function completeYorkJob(processed: number, successful: number, failed: number) {
  if (!currentTaskId) return;

  await fetch(`${TASK_ORCHESTRATOR_URL}/api/tasks/${currentTaskId}/status`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      status: 'completed',
      details: `Processed: ${processed}, Successful: ${successful}, Failed: ${failed}`
    })
  });
}
```

### Example 2: Python Agent

```python
import requests

TASK_ORCHESTRATOR_URL = 'http://localhost:9900'

def report_task_start(title, description, agent_name):
    response = requests.post(
        f'{TASK_ORCHESTRATOR_URL}/api/webhook/task',
        json={
            'title': title,
            'description': description,
            'priority': 'medium',
            'source': agent_name,
            'metadata': {}
        }
    )
    return response.json().get('taskId')

def report_task_complete(task_id, details):
    requests.patch(
        f'{TASK_ORCHESTRATOR_URL}/api/tasks/{task_id}/status',
        json={'status': 'completed', 'details': details}
    )

# Usage
task_id = report_task_start('Process Images', 'Processing 100 product images', 'image-processor')
# ... do work ...
report_task_complete(task_id, 'Processed 100 images successfully')
```

### Example 3: Shell Script Agent

```bash
#!/bin/bash

TASK_ORCHESTRATOR_URL="http://localhost:9900"

# Start task
TASK_ID=$(curl -s -X POST "${TASK_ORCHESTRATOR_URL}/api/webhook/task" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup Database",
    "description": "Creating daily database backup",
    "priority": "high",
    "source": "backup-agent"
  }' | jq -r '.taskId')

echo "Task started: $TASK_ID"

# Do work
pg_dump mydb > backup.sql

# Complete task
curl -s -X PATCH "${TASK_ORCHESTRATOR_URL}/api/tasks/${TASK_ID}/status" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "details": "Database backup created successfully"}'
```

## Integration Checklist

For each agent, ensure:

- [ ] **Task Start** - Report when work begins
- [ ] **Status Updates** - Update to `in_progress` when actively working
- [ ] **Progress Updates** - Optional but recommended for long-running jobs
- [ ] **Task Completion** - Report `completed` when done successfully
- [ ] **Failure Handling** - Report `failed` if work fails
- [ ] **Metadata** - Include agent port and useful context
- [ ] **Error Handling** - Don't crash if orchestrator is unavailable

## Agent Registry

Make sure your agent is registered in the Task Orchestrator's `AGENT_REGISTRY`:

```typescript
// /root/DW-Agents/agent-task-orchestrator/task-orchestrator-agent.ts
const AGENT_REGISTRY = {
  'your-agent-name': {
    port: 9999,
    capabilities: ['feature1', 'feature2', 'keyword-trigger']
  }
};
```

## Testing Your Integration

1. Start your agent
2. Trigger some work
3. Check Task Orchestrator dashboard: http://45.61.58.125:9900/
4. Verify you see:
   - ✅ Task appears with your agent name
   - ✅ Status updates to `in_progress`
   - ✅ Progress bar shows (if applicable)
   - ✅ Task completes with status `completed`

## Currently Integrated Agents

- ✅ **York** (port 7234) - Full integration
- ✅ **Task Orchestrator** (port 9900) - Self-monitoring
- ⏳ **Shopify Store** (port 7238) - Pending
- ⏳ **Digital Samples** (port 9879) - Pending
- ⏳ **Purchasing** (port 9880) - Pending
- ⏳ **Marketing** (port 9881) - Pending
- ⏳ **Legal** (port 9878) - Pending

## Need Help?

See `/root/DW-Agents/shared-task-reporter.ts` for the full TypeScript implementation.