Agent Spawning & Orchestration

# 1. Connect your OpenClaw gateway
# Go to: Dashboard > Integrations > OpenClaw > Connect Gateway

# 2. Open Mission Control
# Dashboard > Mission Control

# 3. Chat with Mission Control to spawn agents automatically
# Just describe your task in natural language!

# From Mission Control (Chat-First Approach):
# Simply type your task in the chat input:
#    "Analyze the latest market trends and create a summary report"
#
# Mission Control AI will:
# 1. Detect your intent (coding, research, analysis, etc.)
# 2. Automatically spawn the right agent type
# 3. Show real-time progress in the timeline
# 4. Return results when complete
#
# The agent runs on your OpenClaw gateway and reports back to NervePay.
# You'll see real-time status updates in the timeline.

# For multi-step workflows (Chat-First or API):
#
# Option 1: Natural Language (Recommended)
# Just describe your complex project in chat:
# "Build a complete user authentication system with database schema,
#  API endpoints, and tests"
#
# Option 2: Direct API (Advanced Users)
# Define your PRD (Product Requirements Document) in JSON:

{
  "objective": "Build a complete user authentication system",
  "tasks": [
    {
      "id": "task-1",
      "title": "Design database schema",
      "description": "Create tables for users, sessions, and tokens",
      "priority": 10,
      "depends_on": []
    },
    {
      "id": "task-2",
      "title": "Implement authentication API",
      "description": "Build login, logout, and session validation endpoints",
      "priority": 8,
      "depends_on": ["task-1"]
    },
    {
      "id": "task-3",
      "title": "Write tests",
      "description": "Unit and integration tests for auth flows",
      "priority": 6,
      "depends_on": ["task-2"]
    }
  ]
}

# 4. Enable "Auto-start" to begin execution immediately
# 5. Click "Create & Start"

# Real-time monitoring in Mission Control:
# - Timeline view shows all agent activity
# - Task board shows orchestration progress (Inbox → Assigned → In Progress → Review → Done)
# - Click any task to see details, logs, and results

# Task dependencies are resolved automatically:
# - Tasks only start when all dependencies are completed
# - Results from completed tasks are passed to dependent tasks
# - Failed tasks are marked and don't block unrelated work

import { useApi } from "@/lib/hooks/use-api";
import { spawnAgentSession } from "@/lib/gateway/gateway-api";
import { usePersistentGateway } from "@/lib/hooks/use-persistent-gateway";

function MyComponent() {
  const api = useApi();
  const { client, status } = usePersistentGateway();

  // Spawn a single agent
  const handleSpawn = async () => {
    if (!client?.isConnected()) {
      alert("Gateway not connected");
      return;
    }

    const result = await spawnAgentSession(client, {
      task: "Research AI agents and create a summary",
      label: "Research Agent",
      runTimeoutSeconds: 3600,
    });

    console.log("Session started:", result.sessionKey);
  };

  // Create an orchestration
  const handleOrchestration = async () => {
    const orchestration = await api.createOrchestration({
      gateway_id: "your-gateway-id",
      name: "My Orchestration",
      prd: {
        objective: "Complete the task",
        tasks: [
          {
            id: "task-1",
            title: "Step 1",
            description: "Do the first thing",
            priority: 10,
            depends_on: []
          }
        ]
      }
    });

    // Start it
    await api.startOrchestration(orchestration.id);
  };

  return (
    <div>
      <button onClick={handleSpawn} disabled={status !== "connected"}>
        Spawn Agent
      </button>
      <button onClick={handleOrchestration}>
        Create Orchestration
      </button>
    </div>
  );
}

# Best Practices:

1. Task Design
   - Write clear, specific task descriptions
   - Include acceptance criteria
   - Set realistic timeouts (60s - 1 hour typical)
   - Use labels to identify sessions

2. Dependencies
   - Keep dependency chains short (< 5 levels deep)
   - Avoid circular dependencies
   - Higher priority = runs first when unblocked

3. Monitoring
   - Check Mission Control timeline regularly
   - Review task board for stuck tasks
   - Enable notifications for task failures
   - Use the activity log for debugging

4. Gateway Management
   - Don't overload: max 8 concurrent agents per gateway (default)
   - Connect multiple gateways for higher throughput
   - Use local gateways for fast response times
   - Monitor gateway health in Integrations panel

# Common Issues:

# 1. "Gateway not connected"
# Solution: Go to Integrations > OpenClaw and ensure your gateway is connected
# Check that the gateway is running: openclaw gateway status

# 2. "Request timed out"
# Solution: The gateway may be overloaded or unreachable
# - Check network connectivity
# - Reduce max_concurrent_agents in gateway settings
# - Increase timeout value

# 3. "Gateway token expired"
# Solution: Refresh the gateway token
# - Go to Integrations > OpenClaw > select gateway > "Refresh Token"
# - Or disconnect and reconnect the gateway

# 4. Orchestration stuck in "running" state
# Solution: Check for failed tasks blocking dependencies
# - Open Mission Control > Task Board
# - Look for tasks in "failed" state
# - Click task to see error details
# - Retry failed tasks or adjust dependencies