# Engine Health/Status/Version API Spec

Health, status, version, and readiness endpoints for the kollabor-engine HTTP server.

**Authentication:** All endpoints exempt from auth (see `server.py:44`).

**Reference Implementation:** `packages/kollabor-engine/src/kollabor_engine/server.py`

**Test:** `tests/test_engine_health_api.py` - All tests passing

---

## GET /health

Liveness check - confirms the engine process is running.

**Implementation:** `server.py:78-80`

```bash
curl http://localhost:7433/health
```

**Response:**

```json
{
  "status": "healthy",
  "uptime": 3600
}
```

| Field    | Type   | Description                          |
|----------|--------|--------------------------------------|
| status   | string | Always `"healthy"`                   |
| uptime   | int    | Seconds since engine started         |

**Use Cases:**
- Kubernetes liveness probes
- Load balancer health checks
- Monitoring dashboards

---

## GET /status

Engine information plus aggregated stats across all active sessions.

**Implementation:** `server.py:100-121`

```bash
curl http://localhost:7433/status
```

**Response:**

```json
{
  "version": "0.1.0",
  "sessions": 2,
  "uptime": 3600,
  "providers": ["anthropic", "openai"],
  "mcp_servers": {
    "memory": "connected",
    "filesystem": "connected"
  },
  "session_ids": ["sess-abc123", "sess-def456"]
}
```

| Field        | Type   | Description                              |
|--------------|--------|------------------------------------------|
| version      | string | Engine version                           |
| sessions     | int    | Number of active sessions                |
| uptime       | int    | Seconds since engine started             |
| providers    | list   | Unique provider types across sessions    |
| mcp_servers  | dict   | MCP server name -> "connected" status    |
| session_ids  | list   | List of active session IDs               |

**Implementation Notes:**
- Providers: aggregated from `session.profile.provider` for all sessions
- MCP servers: collected from `session.mcp_integration.mcp_servers.keys()` for all sessions
- Version: from `importlib.metadata.version("kollabor-engine")`

---

## GET /version

Engine version and all dependency versions.

**Implementation:** `server.py:82-98`

```bash
curl http://localhost:7433/version
```

**Response:**

```json
{
  "version": "0.1.0",
  "engine": "0.1.0",
  "kollabor_ai": "0.1.0",
  "kollabor_agent": "0.1.0",
  "kollabor_events": "0.1.0",
  "python": "3.12.8"
}
```

| Field           | Type   | Description                              |
|-----------------|--------|------------------------------------------|
| version         | string | Engine version (alias for engine)        |
| engine          | string | Engine version                           |
| kollabor_ai     | string | kollabor-ai package version              |
| kollabor_agent  | string | kollabor-agent package version           |
| kollabor_events | string | kollabor-events package version          |
| python          | string | Python runtime version                   |

**Implementation Notes:**
- All versions from `importlib.metadata.version()`
- Falls back to "unknown" if package not found
- Python version from `sys.version.split()[0]`

---

## GET /ready

Readiness check - verifies engine is ready to handle requests.

**Implementation:** `server.py:123-134`

```bash
curl http://localhost:7433/ready
```

**Response:**

```json
{
  "ready": true,
  "checks": {
    "profiles": "ok",
    "sessions": "idle"
  }
}
```

| Field   | Type   | Description                                    |
|---------|--------|------------------------------------------------|
| ready   | bool   | True if profiles exist                         |
| checks  | dict   | Individual check results                       |
| profiles| string | "ok" if profiles configured, "none" otherwise   |
| sessions| string | "ok" if sessions exist, "idle" otherwise       |

**Use Cases:**
- Kubernetes readiness probes
- Service mesh traffic routing
- Startup probe delays

**Implementation Notes:**
- Ready = at least one LLM profile configured
- Sessions optional (engine is ready even with 0 sessions)

---

## Authentication

All four endpoints exempt from auth (see `server.py:44`):

```python
if request.url.path in ("/health", "/version", "/status", "/ready", "/"):
    return await call_next(request)
```

**Testing:**
```bash
# Works without auth
curl http://localhost:7433/health

# Also works with invalid auth
curl -H "Authorization: Bearer invalid" http://localhost:7433/health

# Protected endpoints still require auth
curl http://localhost:7433/sessions  # Returns 401
```

---

## Testing

Run the full test suite:

```bash
python tests/test_engine_health_api.py
```

Tests cover:
- /health returns status: healthy and uptime
- /version returns all package versions
- /status returns sessions, providers, mcp_servers, version
- /ready returns ready state with checks
- All endpoints work without auth header
- Protected endpoints still require auth

---

## Related Files

| File                                    | Lines  | Description                     |
|-----------------------------------------|--------|---------------------------------|
| `server.py`                             | 78-134 | Endpoint implementations        |
| `server.py`                             | 41-56  | Auth middleware (exemptions)    |
| `server.py`                             | 17-24  | Global state (_start_time, etc) |
| `session.py`                            | 289-302| session.to_dict() for stats     |
| `profile_manager.py`                    | 32-66  | LLMProfile.provider field       |
| `auth.py`                               | 14-30  | Token generation/validation     |
| `tests/test_engine_health_api.py`       | all    | Test suite                      |
