JBot WebSocket Protocol

1. Verbindungsaufbau & Authentifizierung

Der JBot WebSocket-Server ist ein asynchroner Server (basierend auf der Python-Bibliothek websockets), der sowohl TCP-basierte als auch Unix-Domain-Socket-Verbindungen akzeptiert. Clients erhalten nach erfolgreichem Handshake eine ready-Nachricht mit einer zugewiesenen chat_id und client_id.

Verbindungs-URLs

TCP (ws:// / wss://)

ws://<host>:<port><path>?client_id=<id>&token=<token>
wss://<host>:<port><path>?client_id=<id>&token=<token>

• host: Standardmäßig 127.0.0.1 (konfigurierbar)
• port: Standardmäßig 8765
• path: Standardmäßig / (konfigurierbar)
• wss://: Verfügbar wenn ssl_certfile und ssl_keyfile konfiguriert sind

Unix Domain Socket

unix:<socket_path><path>?client_id=<id>&token=<token>

• Nur verfügbar wenn unix_socket_path gesetzt ist
• Socket-Pfad muss absolut sein, wird mit chmod 0o600 gesichert

Query-Parameter

Authentifizierung

1. Statischer Token
Der Client sendet den Token als Query-Parameter: ?token=mein-geheimer-token. Der Vergleich erfolgt mittels hmac.compare_digest (timing-safe).

2. Ausgestellte Kurzzeit-Tokens
Wenn token_issue_path konfiguriert ist, kann der Client vor dem WebSocket-Handshake ein kurzlebiges Token per HTTP abrufen:

GET <path> (z. B. /issue-token)
Authorization: Bearer <token_issue_secret>

{
  "token": "<short-lived-token>",
  "expires_in": 300
}

• token_ttl_s: Gültigkeitsdauer in Sekunden (30–86.400, Standard: 300)
• Tokens sind single-use – nach Verwendung ungültig

3. Kein Token
Wenn websocket_requires_token: false gesetzt ist, sind Verbindungen auch ohne Token erlaubt.

4. Wildcard-Host-Schutz
Wenn host auf 0.0.0.0 oder :: gesetzt ist, muss entweder token oder token_issue_secret gesetzt sein – andernfalls lehnt die Konfigurationsvalidierung ab.

allow_from – Client-ID-Autorisierung

{
  "websocket": {
    "allow_from": ["*"]
  }
}

• ["*"]: Alle Clients erlaubt (Standard)
• ["client-a", "client-b"]: Nur Clients mit diesen IDs

Die ready-Nachricht

Nach erfolgreichem WebSocket-Upgrade sendet der Server sofort:

{
  "event": "ready",
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_id": "mein-client-1"
}

Konfigurationsreferenz

Ping/Pong

Der Server sendet automatisch WebSocket-Ping-Frames im konfigurierten Intervall. Clients müssen mit Pong antworten. Bei Timeout wird die Verbindung getrennt.

Verbindungsabbau

Bei Verbindungsabbau wird der Client aus allen Chat-Subscriptions entfernt. Eine neue Verbindung kann sich mit attach wieder in bestehende Sessions einklinken.

2. Client → Server Nachrichten

Der JBot WebSocket-Server akzeptiert zwei Nachrichtenformate:

1. JSON-Envelopes (empfohlen): JSON-Objekte mit einem type-Feld
2. Legacy Plain-Text (einfach): Rohe Textstrings oder {"content": "..."}-Objekte

Legacy Plain-Text

Einfache Textnachrichten ohne type-Feld werden als Chat-Nachricht an die Default-Session gesendet.

Hallo JBot, was kannst du?

Oder als JSON-Objekt (erkannt an content/text/message-Key ohne type):

{"content": "Hallo JBot"}

JSON-Envelopes

Alle modernen Nachrichten verwenden dieses Format:

{
  "type": "<typ>",
  "chat_id": "<uuid>",
  "content": "<nachricht>",
  ...
}

message – Chat-Nachricht senden

{
  "type": "message",
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Erkläre mir JBot",
  "media": [
    { "data_url": "data:image/png;base64,...", "name": "screenshot.png" }
  ],
  "webui": true,
  "turn_id": "optional-turn-id",
  "cli_apps": "optional-cli-apps",
  "mcp_presets": "optional-mcp-presets",
  "image_generation": { "enabled": true, "aspect_ratio": "16:9" }
}

Event-Ablauf: goal_status: running → delta / reasoning_delta → message → turn_end → goal_status: idle

new_chat – Neue Session erstellen

{"type": "new_chat"}

attach – Bestehender Session beitreten

{"type": "attach", "chat_id": "550e8400-e29b-41d4-a716-446655440000"}

fork_chat – Chat abzweigen

{"type": "fork_chat", "chat_id": "<quell-uuid>"}

set_workspace_scope – Workspace ändern

{
  "type": "set_workspace_scope",
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/home/user/projects/meinprojekt"
}

transcribe_audio – Audio-Transkription

{"type": "transcribe_audio", ...}

Error-Antworten

{"event": "error", "detail": "invalid chat_id", "reason": "malformed"}

3. Server → Client Events

Alle vom Server gesendeten Nachrichten sind JSON-Objekte mit einem event-Feld.

ready / attached

{"event": "ready", "chat_id": "...", "client_id": "..."}
{"event": "attached", "chat_id": "..."}

Streaming: delta / stream_end

{"event": "delta", "chat_id": "...", "text": "JBot", "stream_id": "..."}
{"event": "stream_end", "chat_id": "...", "text": "JBot ist...", "stream_id": "..."}

Reasoning: reasoning_delta / reasoning_end

{"event": "reasoning_delta", "chat_id": "...", "text": "Ich analysiere..."}
{"event": "reasoning_end", "chat_id": "..."}

Lifecycle: goal_status / turn_end / goal_state

{"event": "goal_status", "status": "running", "started_at": 1712000000.123}
{"event": "turn_end", "chat_id": "...", "latency_ms": 1234, "goal_state": {...}}
{"event": "goal_status", "status": "idle"}

Fan-Out-Verhalten

• Events mit chat_id nur an abonnierte Clients
• runtime_model_updated und globale session_updated an alle verbundenen Clients
• goal_state / goal_status ohne Subscriber: nur Log

4. Nachrichtenfluss & Lebenszyklus

1. Verbindungsaufbau

2. Einfache Chat-Nachricht (Legacy)

3. Multi-Chat mit JSON-Envelopes

4. Reasoning-Modelle

reasoning_delta / reasoning_end erscheinen vor dem normalen delta-Stream. Clients sollten Reasoning-Text visuell abgrenzen (z. B. zusammenklappbarer "Thinking"-Block).

5. Tool-Ausführung mit Fortschritt

6. Reconnect & Session-Wiederherstellung

7. Multi-Client Fan-Out

Zustandsautomat (Client-Sicht)

Globale Broadcast-Events

• runtime_model_updated – bei Modell-Wechsel
• session_updated – bei globalen Session-Änderungen

5. Medien-Upload-Spezifikation

Bild- und Video-Uploads direkt im WebSocket-Frame als Base64-kodierte Data-URLs im media-Array des message-Envelopes.

{
  "type": "message",
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Analysiere dieses Bild",
  "media": [
    { "data_url": "data:image/png;base64,...", "name": "screenshot.png" }
  ]
}

Unterstützte MIME-Typen & Limits

Bilder

Ausgeschlossen: image/svg+xml (Sicherheitsgründe: XSS-Risiko).

Videos

Pro-Nachricht-Limits

Fehlerbehandlung

Server-seitige Verarbeitung

1. MIME-Type aus Data-URL extrahieren
2. Validierung gegen Allowlist
3. Größenprüfung (vor Dekodieren anhand Base64-Länge)
4. Speicherung unter <media_dir>/websocket/<uuid>_<name>
5. Pfade als media an Agenten weitergeben
6. In Antwort: media und/oder media_urls mit signierten HTTP-URLs

Base64-Overhead

original_bytes ≈ base64_chars × 3 / 4

Eine 8 MB große Datei erzeugt ≈10.9 MB Base64 (×1.37 Overhead).

6. Node.js-Referenzimplementierung

Vollständiger JBot WebSocket-Client in Node.js unter Verwendung der ws-Bibliothek. Abhängigkeit:

npm install ws

Alternativ kann die in Node.js 22+ eingebaute WebSocket-API verwendet werden.

Basis-Client: Verbinden und Nachricht senden

// client-basic.js
import WebSocket from 'ws';

const HOST = '127.0.0.1', PORT = 8765, TOKEN = 'mein-token';
const url = `ws://${HOST}:${PORT}/?client_id=nodejs-app&token=${TOKEN}`;
const ws = new WebSocket(url);

ws.on('open', () => console.log('✅ Verbunden mit JBot'));
ws.on('message', (data) => {
  console.log(`📩 [${JSON.parse(data).event}]`, data.toString());
});
ws.on('close', (c, r) => console.log(`🔌 Geschlossen: ${c} ${r}`));
ws.on('error', (e) => console.error('❌', e.message));

setTimeout(() => ws.send('Hallo JBot, was kannst du?'), 5000);

JBotClient – Vollständiger Client

Der vollständige Source-Code inklusive TypeScript-Typdefinitionen ist als Markdown verfügbar: websocket/06-nodejs-client.md

Kern-API

Event-Handler (überschreibbar via Konstruktor)

onReady(chatId, clientId)
onMessage(msg)
onDelta(msg)
onStreamEnd(msg)
onReasoning(type, msg)       // type: "delta" | "end"
onToolHint(msg)
onProgress(msg)
onFileEdit(msg)
onTurnEnd(msg)
onGoalState(msg)
onGoalStatus(msg)
onSessionUpdated(msg)
onRuntimeModelUpdated(msg)
onError(msg)
onClose(code, reason)

Implementierungshinweise

1. JSON-Envelopes bevorzugen – Legacy Plain-Text nur für Demos
2. Auf ready warten – Keine Nachrichten vor ready senden
3. Streaming akkumulieren – Deltas sammeln, stream_end enthält finalen Text
4. Reasoning abgrenzen – Vor dem normalen Antwort-Stream
5. Turn-Lebenszyklus – Beginnt mit goal_status: running, endet mit idle
6. Fehler abfangen – error-Events immer behandeln
7. Reconnect – chat_id speichern, nach Reconnect mit attach subscriben