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:**
  ```json
  {
    "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:**
  ```json
  {
    "status": "ok",
    "timestamp": "2023-10-27T10:00:00.000Z"
  }
  ```

### `GET /api/agents`

Lists available agents.

- **Method:** `GET`
- **URL:** `/api/agents`
- **Response Body Example:**
  ```json
  [
    {
      "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:**
  ```json
  {
    "agent": "Coder",
    "task": "Fix bug in user authentication",
    "repo": "owner/repo-name"
  }
  ```
- **Response Body Example (Success):**
  ```json
  {
    "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:**
  ```json
  {
    "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:**
  ```json
  [
    {
      "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:**
  ```json
  {
    "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:**
    ```bash
    git clone <repository-url>
    cd vibn-agent-runner
    ```

2.  **Install dependencies:**
    ```bash
    npm install
    ```
    or
    ```bash
    yarn install
    ```

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

4.  **Build the project (if TypeScript):**
    ```bash
    npm run build
    ```
    or
    ```bash
    yarn build
    ```

5.  **Start the application:**
    ```bash
    npm start
    ```
    or
    ```bash
    yarn start
    ```

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