vibn-agent-runner/PROJECT.md

vibn-agent-runner Project Documentation

What it does

The vibn-agent-runner is a service responsible for executing tasks or "agents" within the Vibn ecosystem. It likely receives requests to run specific agents, manages their execution, and reports back their status or results. This service acts as a crucial component for extending Vibn's capabilities through custom or predefined agents.

API Endpoints

GET /api/status

Retrieves server status and job statistics.

• Method: GET
• URL: /api/status
• Response Body Example:

  {
    "total_jobs": 100,
    "by_status": {
      "queued": 10,
      "running": 5,
      "completed": 80,
      "failed": 5
    },
    "uptime_seconds": 3600,
    "agents": ["Coder", "PM", "Marketing"]
  }
  

GET /health

Health check endpoint.

• Method: GET
• URL: /health
• Response Body Example:

  {
    "status": "ok",
    "timestamp": "2023-10-27T10:00:00.000Z"
  }
  

GET /api/agents

Lists available agents.

• Method: GET
• URL: /api/agents
• Response Body Example:

  [
    {
      "name": "Coder",
      "description": "An agent that writes and modifies code.",
      "tools": ["read_file", "write_file", "replace_in_file", "list_directory", "find_files", "search_code", "execute_command", "git_commit_and_push", "gitea_create_issue", "gitea_list_issues", "gitea_close_issue"]
    }
  ]
  

POST /api/agent/run

Submits a new job to run an agent.

• Method: POST
• URL: /api/agent/run
• Request Body Example:

  {
    "agent": "Coder",
    "task": "Fix bug in user authentication",
    "repo": "owner/repo-name"
  }
  

• Response Body Example (Success):

  {
    "jobId": "unique-job-id",
    "status": "queued"
  }
  

GET /api/jobs/:id

Retrieves the status of a specific job.

• Method: GET
• URL: /api/jobs/:id
• Response Body Example:

  {
    "id": "unique-job-id",
    "agent": "Coder",
    "task": "Fix bug in user authentication",
    "repo": "owner/repo-name",
    "status": "running",
    "progress": "Executing tests...",
    "createdAt": "2023-10-27T10:00:00.000Z"
  }
  

GET /api/jobs

Lists recent jobs.

• Method: GET
• URL: /api/jobs
• Query Parameters:
  • limit: (Optional) Number of jobs to return (default: 20)
• Response Body Example:

  [
    {
      "id": "job-id-1",
      "agent": "Coder",
      "task": "Implement feature X",
      "status": "completed"
    },
    {
      "id": "job-id-2",
      "agent": "PM",
      "task": "Write project brief",
      "status": "running"
    }
  ]
  

POST /webhook/gitea

Gitea webhook endpoint to trigger agents from issue events.

• Method: POST
• URL: /webhook/gitea
• Headers:
  • X-Gitea-Event: e.g., issues
  • X-Gitea-Signature: HMAC-SHA256 signature (if WEBHOOK_SECRET is set)
• Request Body: Gitea webhook payload (JSON)
• Response Body Example:

  {
    "jobId": "unique-job-id",
    "agent": "Coder",
    "event": "issues"
  }
  

How to run locally

To run the vibn-agent-runner locally, follow these steps:

1. Clone the repository:

   git clone <repository-url>
   cd vibn-agent-runner
   

2. Install dependencies:

   npm install
   

   or

   yarn install
   

3. Configure environment variables: Copy the .env.example file to .env and update the values as needed.

   cp .env.example .env
   

4. Build the project (if TypeScript):

   npm run build
   

   or

   yarn build
   

5. Start the application:

   npm start
   

   or

   yarn start
   

The application should now be running, typically accessible at http://localhost:3000 (or another port specified in your environment configuration).