agenthub/docs/specs/2026-06-25-agenthub-network-mode-design.md

AgentHub Network Mode — Design Spec

Datum: 2026-06-25
Status: Entwurf – zur Freigabe
Ziel: AgentHub für parallele Agenten-Sessions auf mehreren Geräten im gleichen lokalen Netzwerk verwendbar machen (z. B. Kimi auf Mac + Kimi auf Windows).

---

1. Zusammenfassung

AgentHub bleibt ein dateibasiertes Tool. Ein Gerät im Netzwerk (hier: der Mac) hostet das Projektverzeichnis inklusive .agenthub/ und bietet einen optionalen Fastify-Server an. Andere Geräte (z. B. Windows) nutzen die CLI im Remote-Modus und sprechen den Server über HTTP an.

Lokaler Dateizugriff bleibt der Default. Remote-Modus ist opt-in über --server <url> oder die Umgebungsvariable AGENTHUB_SERVER.

---

2. Architektur

┌─────────────────────┐         HTTP          ┌─────────────────────┐
│  Kimi auf Windows   │  ◄──────────────────► │  AgentHub Server    │
│  agenthub --server  │                      │  auf Mac (0.0.0.0)  │
│  http://mac:3377    │                      │                     │
└─────────────────────┘                      │  liest/schreibt     │
                                             │  .agenthub/ auf Mac │
                                             │  (Dateien = SSOT)   │
                                             └─────────────────────┘

• Single Source of Truth: Die Markdown-Dateien auf dem Mac.
• Server: Führt die gleichen Lese-/Schreiboperationen aus wie die lokale CLI und aktualisiert den SQLite-Index.
• Client (Remote-Modus): Dünne HTTP-Schicht; keine eigene Geschäftslogik.

---

3. CLI-Änderungen

Globaler --server-Flag

agenthub --server http://192.168.1.42:3377 task list
agenthub --server http://mac.local:3377 status --update

Alternativ per Env-Variable:

export AGENTHUB_SERVER=http://192.168.1.42:3377
agenthub task create --title "Foo"

Ausgenommene Befehle

• agenthub init bleibt immer lokal. Das Projekt muss auf dem Host-Rechner initialisiert werden, bevor andere Geräte remote darauf zugreifen.

Fehlerbehandlung

• Server nicht erreichbar → "AgentHub server at http://... is not reachable. Is 'agenthub server start --host 0.0.0.0' running?"
• HTTP-Fehler → Statuscode + Server-Antwort ausgeben.
• --server fehlt auf Windows → Hinweis, dass entweder --server gesetzt oder ein SMB-Share genutzt werden muss.

---

4. Server-Änderungen

Start-Kommando

agenthub server start --host 0.0.0.0 --port 3377

• --host ist neu; Default: 127.0.0.1.
• --port bleibt wie gehabt; Default: 3377.
• Für LAN-Nutzung muss --host 0.0.0.0 gesetzt werden.

Endpoints

Methode	Endpoint	Zweck
GET	/status	Aktuellen Status zurückgeben
POST	/status/update	Status neu generieren
GET	/tasks	Tasks auflisten
POST	/tasks	Task erstellen
GET	/tasks/:id	Task anzeigen
PATCH	/tasks/:id	Task aktualisieren (claim, done, status)
GET	/handoffs	Handoffs auflisten
POST	/handoffs	Handoff erstellen
GET	/handoffs/:id	Handoff anzeigen
GET	/decisions	Decisions auflisten
POST	/decisions	Decision erstellen
GET	/memory	Memory-Einträge auflisten
POST	/memory	Memory-Eintrag erstellen
GET	/memory/search?q=...	Volltextsuche
POST	/delegate	Delegation vorschlagen/auto

Alle Endpoints verwenden die bestehenden Core-Funktionen (taskCreate, taskList, etc.).

Auth (MVP)

• Keine Authentifizierung im MVP.
• Header-Struktur wird so gebaut, dass später Authorization: Bearer <token> einfach ergänzt werden kann.

---

5. Client-Modus

Jeder CLI-Befehl entscheidet anhand von --server / AGENTHUB_SERVER, ob er lokal arbeitet oder den RemoteClient nutzt.

Beispiel task create:

if (serverUrl) {
  await remoteClient.createTask(serverUrl, options);
} else {
  await localTaskCreate(cwd, options);
}

Der RemoteClient ist eine kleine Wrapper-Klasse um fetch.

---

6. Tests

1. Server-Routen-Tests: Fastify-App direkt testen, ohne Port zu öffnen.
2. RemoteClient-Tests: Client gegen einen gemockten Server testen.
3. E2E-Test:
   • Temporäres Projekt auf dem Mac initialisieren.
   • Server starten (--host 127.0.0.1 reicht für E2E).
   • CLI mit --server http://127.0.0.1:<port> aufrufen.
   • Prüfen, dass die Datei im Projektverzeichnis landet.

---

7. Beispiel-Workflow

Auf dem Mac:

cd ~/my-project
agenthub init --project-name my-project
agenthub server start --host 0.0.0.0 --port 3377

Auf Windows:

$env:AGENTHUB_SERVER="http://192.168.1.42:3377"
agenthub task create --title "Implement Windows bypass check" --role implementer
agenthub status

Auf dem Mac kann parallel weiter lokal gearbeitet werden:

agenthub task list
agenthub task done TSK-0001

---

8. Offene Punkte / Folgearbeiten

1. Auth/Token-Support für unsichere Netzwerke.
2. Bonjour/mDNS-Autodiscovery des Servers.
3. Konflikterkennung bei gleichzeitigen Schreibzugriffen (z. B. via ETags).
4. HTTPS/SSL für Produktivnetzwerke.