# 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

```text
┌─────────────────────┐         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

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

Alternativ per Env-Variable:

```bash
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

```bash
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`:

```typescript
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:**

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

**Auf Windows:**

```bash
$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:**

```bash
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.