Deploymentcenter/docs/BUGTRACKER_INTEGRATION_GUIDE.md

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

⚠️ Geändert in Version 2.0 — POST /api/bugtracker/v1/report und GET /api/bugtracker/v1/projects verlangen jetzt zwingend ein Token mit dem passenden Scope; Aufrufe ohne Token liefern 401 unauthorized. Das Antwortformat wurde vereinheitlicht. Die aktuelle, vollständige Beschreibung steht im Agenten-Handbuch und unter /api/openapi.json. Umstellungsschritte: UPGRADE.md.

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:

{
  "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:

{
  "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:

{
  "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

{
  "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")

{
  "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:

{
  "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

GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01

B. Updating Status & Details (POST ?action=update)

{
  "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)

{
  "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)

{
  "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

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

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.