Deploymentcenter/public/docs/bugtracker.md

# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API

This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.

---

## 📌 Executive Overview for AI Agents

As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center.

### Core Capabilities:
1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks.
2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication.
3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`).
4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments.

---

## 🔑 1. Token Provisioning API

Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**.

### Endpoint: `POST /api/tokens/v1/provision`

Header: `Authorization: Bearer <MASTER_TOKEN>`

#### Request Payload:
```json
{
  "parent_token": "dc_master_myapp_dev_agent_001",
  "name": "Codebase Refactoring Agent Token",
  "environment": "development",
  "scopes": ["bugtracker:report", "bugtracker:manage"],
  "expires_in_hours": 24
}
```

#### Response:
```json
{
  "status": "success",
  "token_id": "tok_s_8912ab",
  "raw_token": "dc_sub_myapp_refactor_agent_991",
  "scopes": ["bugtracker:report", "bugtracker:manage"],
  "environment": "development",
  "expires_at": "2026-08-07 21:00:00"
}
```

---

## 📂 1.5. Discovering Monitored Projects API

Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center.

### Endpoint: `GET /api/bugtracker/v1/projects.php`

#### Response:
```json
{
  "status": "success",
  "count": 4,
  "projects": [
    {
      "id": 1,
      "slug": "myapp",
      "name": "My Application Deluxe",
      "notes": "Hauptanwendung für Desktop und Server"
    },
    {
      "id": 2,
      "slug": "polytrader",
      "name": "PolyTrader Suite Pro",
      "notes": "Trading- und Handelssystem Client"
    },
    {
      "id": 3,
      "slug": "predictalytics",
      "name": "Predictalytics Engine",
      "notes": "Datenanalyse und Vorhersage Dienst"
    },
    {
      "id": 4,
      "slug": "deploymentcenter",
      "name": "Deployment Center",
      "notes": "Zentrale Verwaltungs- & Update-Plattform"
    }
  ]
}
```

If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`.

---

## 🐛 2. Reporting Bugs, Features & Ideas

### Endpoint: `POST /api/bugtracker/v1/report.php`

Header: `Authorization: Bearer <AGENT_TOKEN>`

### A. Reporting an Unhandled Exception / Bug
```json
{
  "project_slug": "myapp",
  "type": "bug",
  "title": "NullReferenceException in UserAuthService.cs line 42",
  "description": "Triggered when user logs in without an active session object.",
  "error_message": "NullReferenceException: Object reference not set to an instance of an object.",
  "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18",
  "build_version": "v1.4.2-dev",
  "environment": "development",
  "severity": "high",
  "push_id": "push_wf_8912",
  "target_agent": "agent:code-fixer-01",
  "tags": "auth, security, csharp",
  "created_by": "agent:watchdog-monitor"
}
```

### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`)
```json
{
  "project_slug": "myapp",
  "type": "feature_request",
  "title": "Automatische Datenbank-Backups vor FTP Deployments",
  "description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.",
  "build_version": "v1.6.0-roadmap",
  "environment": "development",
  "severity": "idea",
  "push_id": "push_wf_9910",
  "target_agent": "agent:db-optimizer",
  "tags": "database, automation, backup",
  "created_by": "agent:planner"
}
```

#### Response:
```json
{
  "status": "success",
  "item_id": 4,
  "is_new": true,
  "occurrence_count": 1,
  "error_hash": "e2c918a514d89a42f",
  "type": "bug",
  "environment": "development",
  "push_id": "push_wf_8912",
  "message": "New bug reported successfully."
}
```

---

## 📌 3. Managing Items (Fetching, Updating & Commenting)

### Base Endpoint: `/api/bugtracker/v1/manage/index.php`

Header: `Authorization: Bearer <AGENT_TOKEN>`

### A. Fetching Open Items Assigned to an Agent
```http
GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01
```

### B. Updating Status & Details (`POST ?action=update`)
```json
{
  "id": 4,
  "status": "in_progress",
  "severity": "high",
  "push_id": "push_wf_8912",
  "target_agent": "agent:code-fixer-01",
  "tags": "auth, fixed_pending_test",
  "author": "agent:code-fixer-01"
}
```

### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`)
```json
{
  "id": 4,
  "comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.",
  "action_taken": "code_patched",
  "author": "agent:code-fixer-01"
}
```

### D. Marking as Resolved (`POST ?action=resolve`)
```json
{
  "id": 4,
  "resolved_in_build": "v1.4.3-dev",
  "resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.",
  "author": "agent:code-fixer-01"
}
```

---

## 💻 4. Code Implementation Examples for Agents

### Python Example: Automatic Error Reporter Decorator
```python
import requests
import traceback
import sys

DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php"
AGENT_TOKEN = "dc_sub_myapp_agent_live_001"

def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None):
    payload = {
        "project_slug": project_slug,
        "type": "bug",
        "title": f"{type(exc).__name__}: {str(exc)}",
        "error_message": str(exc),
        "stack_trace": traceback.format_exc(),
        "build_version": "v1.4.2",
        "environment": env,
        "severity": "high",
        "push_id": push_id,
        "created_by": "agent:python-runner"
    }
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {AGENT_TOKEN}"
    }
    try:
        r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5)
        return r.json()
    except Exception as e:
        print(f"Failed to report to Deployment Center: {e}", file=sys.stderr)
```

### cURL Example: Submit Feature Request / Idea
```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \
  -H "Authorization: Bearer dc_sub_myapp_agent_live_001" \
  -H "Content-Type: application/json" \
  -d '{
    "project_slug": "myapp",
    "type": "feature_request",
    "title": "Erweiterte Filterung im WebUI Dashboard",
    "severity": "idea",
    "push_id": "push_task_1029",
    "tags": "ui, dashboard",
    "created_by": "agent:dev-assistant"
  }'
```

---

## 🎯 Best Practices for Developer Agents

1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run.
2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas.
3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed.