WebSocket Relay Protokoll

MaxiCore bietet Echtzeit-Event-Streaming über WebSocket. Dies ist der beste Weg, um Task-Fortschritt und Agent-Status zu verfolgen.

Connection

wss://api.maxicore.ch/v2/ws

Mit Authorization:

const token = await getToken();
const ws = new WebSocket(
  `wss://api.maxicore.ch/v2/ws?token=${token}`
);

Oder via Header (falls unterstützt):

const ws = new WebSocket('wss://api.maxicore.ch/v2/ws');
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'Bearer ' + token
  }));
});

Message Format

Alle Messages sind JSON:

{
  "type": "task.progress",
  "timestamp": "2026-03-27T10:30:45Z",
  "agent_id": "agent-123",
  "task_id": "task-456",
  "data": { /* Event-spezifisch */ }
}

Event-Typen

task.started

Task wurde gestartet.

{
  "type": "task.started",
  "task_id": "task-456",
  "agent_id": "agent-123",
  "description": "Process data file"
}

task.progress

Task macht Fortschritt (Steps, Output).

{
  "type": "task.progress",
  "task_id": "task-456",
  "step": 3,
  "total_steps": 10,
  "current_action": "Reading file: data.csv",
  "output": "Processing 1000 rows..."
}

task.completed

Task erfolgreich abgeschlossen.

{
  "type": "task.completed",
  "task_id": "task-456",
  "result": {
    "success": true,
    "summary": "Processed 1000 rows in 2.5 seconds",
    "output_files": ["result.json"]
  },
  "credits_used": 42
}

task.failed

Task ist fehlgeschlagen.

{
  "type": "task.failed",
  "task_id": "task-456",
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File /data/input.csv not found"
  },
  "credits_used": 5
}

agent.online

Agent verbunden / online geworden.

{
  "type": "agent.online",
  "agent_id": "agent-123",
  "timestamp": "2026-03-27T10:30:00Z"
}

agent.offline

Agent getrennt / offline geworden.

{
  "type": "agent.offline",
  "agent_id": "agent-123",
  "timestamp": "2026-03-27T10:35:00Z",
  "reason": "Client disconnected"
}

shield.violation

Shield-Sicherheitsregel verletzt.

{
  "type": "shield.violation",
  "agent_id": "agent-123",
  "task_id": "task-456",
  "violation": {
    "rule_type": "command",
    "pattern": "blocked_pattern",
    "attempted_action": "rm -rf /",
    "severity": "critical"
  }
}

Subscribe zu Events

Sende einen Subscribe-Request nach Connection:

ws.send(JSON.stringify({
  type: 'subscribe',
  filters: {
    agent_id: 'agent-123',
    event_types: ['task.progress', 'task.completed', 'task.failed'],
    workspace_id: 'ws-456'
  }
}));

Ohne Filter: Alle deine Workspace-Events werden gestreamt.

Unsubscribe

ws.send(JSON.stringify({
  type: 'unsubscribe',
  filters: {
    agent_id: 'agent-123'
  }
}));

Heartbeat (Ping/Pong)

Server sendet periodisch Pings. Client sollte Pongs antworten:

ws.addEventListener('ping', (event) => {
  ws.pong(event.data);
});

// Oder
ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Timeout: Bei 3 fehlgeschlagenen Pongs wird die Connection geschlossen.

Beispiel: Task-Überwachung

const token = await getToken();
const ws = new WebSocket(`wss://api.maxicore.ch/v2/ws?token=${token}`);

ws.addEventListener('open', () => {
  // Subscribe zu Task-Events
  ws.send(JSON.stringify({
    type: 'subscribe',
    filters: {
      task_id: 'task-456',
      event_types: ['task.started', 'task.progress', 'task.completed', 'task.failed']
    }
  }));
});

ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'task.started':
      console.log('Task gestartet:', msg.description);
      break;
    case 'task.progress':
      console.log(`Progress: ${msg.step}/${msg.total_steps}`);
      console.log(`Aktion: ${msg.current_action}`);
      break;
    case 'task.completed':
      console.log('Task abgeschlossen!');
      console.log('Ergebnis:', msg.result);
      console.log('Credits verbraucht:', msg.credits_used);
      break;
    case 'task.failed':
      console.error('Task fehlgeschlagen:', msg.error.message);
      break;
  }
});

ws.addEventListener('close', () => {
  console.log('WebSocket geschlossen');
});

Rate Limiting

WebSocket ist nicht rate-limited. Aber zu viele gleichzeitige Subscriptions (> 100) können zur Disconnection führen.

Connection Lifecycle

1. Connect: WebSocket handshake
2. Auth: Token senden (falls nicht in URL)
3. Subscribe: Events filtern
4. Receive: Events empfangen
5. Unsubscribe: Cleanup (optional)
6. Close: Connection beenden

Server hält Connection offen, bis Client disconnectet oder 30 Minuten Inaktivität.