# Symbiont REPL-Leitfaden

## Andere Sprachen


---

Die Symbiont-REPL (Read-Eval-Print Loop) bietet eine interaktive Umgebung zum Entwickeln, Testen und Debuggen von Symbiont-Agenten und DSL-Code.

> **Suchen Sie eine interaktive TUI?** [`symbi shell`](/symbi-shell) (Beta) umhuellt dieselbe `repl_core`-Engine, die dieser Leitfaden behandelt, plus einen LLM-Orchestrator, einen vollstaendigen Befehlskatalog (`/spawn`, `/run`, `/chain`, …) und Remote-Attach. Verwenden Sie die REPL, wenn Sie eine skriptbare JSON-RPC-Oberflaeche fuer die IDE-Integration moechten; verwenden Sie die Shell, wenn Sie konversationelle Autorenerstellung gegen dasselbe Runtime moechten.

## Funktionen

- **Interaktive DSL-Auswertung**: Symbiont-DSL-Code in Echtzeit ausfuehren
- **Agenten-Lebenszyklus-Verwaltung**: Agenten erstellen, starten, stoppen, pausieren, fortsetzen und zerstoeren
- **Ausfuehrungsueberwachung**: Echtzeitueberwachung der Agentenausfuehrung mit Statistiken und Traces
- **Policy-Durchsetzung**: Integrierte Policy-Pruefung und Capability-Gating
- **Sitzungsverwaltung**: REPL-Sitzungen als Snapshot sichern und wiederherstellen
- **JSON-RPC-Protokoll**: Programmatischer Zugriff ueber JSON-RPC via stdio
- **LSP-Unterstuetzung**: Language Server Protocol fuer IDE-Integration

## Erste Schritte

### REPL starten

```bash
# Interaktiver REPL-Modus
symbi repl

# JSON-RPC-Servermodus ueber stdio (fuer IDE-Integration)
symbi repl --stdio
```

> **Hinweis:** Das `--config`-Flag wird noch nicht unterstuetzt. Die Konfiguration wird vom Standard-`symbiont.toml`-Speicherort gelesen. Unterstuetzung fuer benutzerdefinierte Konfiguration ist fuer ein zukuenftiges Release geplant.

### Grundlegende Verwendung

```rust
# Einen Agenten definieren
metadata {
  version = "1.0.0"
  description = "A simple greeting agent"
}

agent greeter(name: String) -> String {
  capabilities = ["greet"]

  policy safe {
    allow: read(name) if true
  }

  with memory = "ephemeral" {
    return greet(name);
  }
}
```

## REPL-Befehle

### Agentenverwaltung

| Befehl | Beschreibung |
|--------|-------------|
| `:agents` | Alle Agenten auflisten |
| `:agent list` | Alle Agenten auflisten |
| `:agent start <id>` | Einen Agenten starten |
| `:agent stop <id>` | Einen Agenten stoppen |
| `:agent pause <id>` | Einen Agenten pausieren |
| `:agent resume <id>` | Einen pausierten Agenten fortsetzen |
| `:agent destroy <id>` | Einen Agenten zerstoeren |
| `:agent execute <id> <behavior> [args]` | Agentenverhalten ausfuehren |
| `:agent debug <id>` | Debug-Informationen fuer einen Agenten anzeigen |

### Ueberwachungsbefehle

| Befehl | Beschreibung |
|--------|-------------|
| `:monitor stats` | Ausfuehrungsstatistiken anzeigen |
| `:monitor traces [limit]` | Ausfuehrungs-Traces anzeigen |
| `:monitor report` | Detaillierten Ausfuehrungsbericht anzeigen |
| `:monitor clear` | Ueberwachungsdaten loeschen |

### Speicherbefehle

| Befehl | Beschreibung |
|--------|-------------|
| `:memory inspect <agent-id>` | Speicherzustand eines Agenten inspizieren |
| `:memory compact <agent-id>` | Speicher eines Agenten komprimieren |
| `:memory purge <agent-id>` | Gesamten Speicher eines Agenten loeschen |

### Webhook-Befehle

| Befehl | Beschreibung |
|--------|-------------|
| `:webhook list` | Konfigurierte Webhooks auflisten |
| `:webhook add` | Einen neuen Webhook hinzufuegen |
| `:webhook remove` | Einen Webhook entfernen |
| `:webhook test` | Einen Webhook testen |
| `:webhook logs` | Webhook-Logs anzeigen |

### Aufzeichnungsbefehle

| Befehl | Beschreibung |
|--------|-------------|
| `:record on <file>` | Sitzungsaufzeichnung in eine Datei starten |
| `:record off` | Sitzungsaufzeichnung beenden |

### Sitzungsbefehle

| Befehl | Beschreibung |
|--------|-------------|
| `:snapshot` | Sitzungs-Snapshot erstellen |
| `:clear` | Sitzung loeschen |
| `:help` oder `:h` | Hilfemeldung anzeigen |
| `:version` | Versionsinformationen anzeigen |

## DSL-Funktionen

### Agenten-Definitionen

```rust
metadata {
  version = "2.1.0"
  description = "Analyzes datasets with privacy protection"
}

agent data_analyzer(data: DataSet, options: AnalysisOptions) -> AnalysisResults {
  capabilities = ["data_read", "analysis"]

  policy privacy {
    allow: read(data) if true
    deny: write(any)
  }

  with memory = "ephemeral", sandbox = "tier1" {
    return analyze(data, options);
  }
}
```

Das Agentenverhalten lebt im `with`-Block des Agenten (und in `function`-Definitionen) --
es gibt kein separates `behavior`-Konstrukt. Richtlinienregeln (`allow` / `deny` /
`require` / `audit`) steuern, was der Agent tun darf. Siehe den
[DSL-Leitfaden](dsl-guide.md) und die [DSL-Spezifikation](dsl-specification.md) fuer die
vollstaendige Grammatik.

### Eingebaute Funktionen

| Funktion | Beschreibung | Beispiel |
|----------|-------------|---------|
| `print(...)` | Werte in die Ausgabe schreiben | `print("Hello", name)` |
| `len(value)` | Laenge von String, Liste oder Map ermitteln | `len("hello")` -> `5` |
| `upper(string)` | String in Grossbuchstaben umwandeln | `upper("hello")` -> `"HELLO"` |
| `lower(string)` | String in Kleinbuchstaben umwandeln | `lower("HELLO")` -> `"hello"` |
| `format(template, ...)` | String mit Argumenten formatieren | `format("Hello, {}!", name)` |

> **Geplante eingebaute Funktionen:** Erweiterte E/A-Funktionen wie `read_file()`, `read_csv()`, `write_results()`, `analyze()` und `transform_data()` sind noch nicht implementiert. Diese sind fuer ein zukuenftiges Release geplant.

### Datentypen

```rust
# Grundtypen
let name = "Alice"          # String
let age = 30               # Integer
let height = 5.8           # Number
let active = true          # Boolean
let empty = null           # Null

# Sammlungen
let items = [1, 2, 3]      # Liste
let config = {             # Map
  "host": "localhost",
  "port": 8080
}

# Zeit- und Groesseneinheiten
let timeout = 30s          # Dauer
let max_size = 100MB       # Groesse
```

## Architektur

### Komponenten

```
symbi repl
├── repl-cli/          # CLI-Schnittstelle und JSON-RPC-Server
├── repl-core/         # Kern-REPL-Engine und Evaluator
├── repl-proto/        # JSON-RPC-Protokolldefinitionen
└── repl-lsp/          # Language Server Protocol Implementierung
```

### Kernkomponenten

- **DslEvaluator**: Fuehrt DSL-Programme mit Laufzeitintegration aus
- **ReplEngine**: Koordiniert Auswertung und Befehlsverarbeitung
- **ExecutionMonitor**: Verfolgt Ausfuehrungsstatistiken und Traces
- **RuntimeBridge**: Integriert sich mit der Symbiont-Laufzeit fuer Policy-Durchsetzung
- **SessionManager**: Verwaltet Snapshots und Sitzungszustand

### JSON-RPC-Protokoll

Die REPL unterstuetzt JSON-RPC 2.0 fuer programmatischen Zugriff:

```json
// DSL-Code auswerten
{
  "jsonrpc": "2.0",
  "method": "evaluate",
  "params": {"input": "let x = 42"},
  "id": 1
}

// Antwort
{
  "jsonrpc": "2.0",
  "result": {"value": "42", "type": "integer"},
  "id": 1
}
```

## Sicherheit & Policy-Durchsetzung

### Capability-Pruefung

Die REPL erzwingt Capability-Anforderungen, die in Agenten-Sicherheitsbloecken definiert sind:

```rust
agent SecureAgent {
  name: "Secure Agent"
  security {
    capabilities: ["filesystem", "network"]
    sandbox: true
  }
}

behavior ReadFile {
  input { path: string }
  output { content: string }
  steps {
    # Dies prueft, ob der Agent die Capability "filesystem" hat
    require capability("filesystem")
    # HINWEIS: read_file() ist eine geplante eingebaute Funktion (noch nicht implementiert).
    # Dieses Beispiel veranschaulicht, wie Capability-Pruefung funktioniert.
    let content = read_file(path)
    return content
  }
}
```

### Policy-Integration

Die REPL integriert sich mit der Symbiont-Policy-Engine, um Zugriffskontrollen und Audit-Anforderungen durchzusetzen.

## Debugging & Ueberwachung

### Ausfuehrungs-Traces

```
:monitor traces 10

Recent Execution Traces:
  14:32:15.123 - AgentCreated [Agent: abc-123] (2ms)
  14:32:15.125 - AgentStarted [Agent: abc-123] (1ms)
  14:32:15.130 - BehaviorExecuted [Agent: abc-123] (5ms)
  14:32:15.135 - AgentPaused [Agent: abc-123]
```

### Statistiken

```
:monitor stats

Execution Monitor Statistics:
  Total Executions: 42
  Successful: 38
  Failed: 4
  Success Rate: 90.5%
  Average Duration: 12.3ms
  Total Duration: 516ms
  Active Executions: 2
```

### Agenten-Debugging

```
:agent debug abc-123

Agent Debug Information:
  ID: abc-123-def-456
  Name: Data Analyzer
  Version: 2.1.0
  State: Running
  Created: 2024-01-15 14:30:00 UTC
  Description: Analyzes datasets with privacy protection
  Author: data-team@company.com
  Available Functions/Behaviors: 5
  Required Capabilities: 2
    - data_read
    - analysis
  Resource Configuration:
    Memory: 512MB
    CPU: 2
    Storage: 1GB
```

## IDE-Integration

### Language Server Protocol

Die REPL bietet LSP-Unterstuetzung fuer IDE-Integration ueber das `repl-lsp` Crate. Der LSP-Server wird separat von der REPL selbst gestartet:

```bash
# Der LSP-Server wird vom repl-lsp Crate bereitgestellt und durch
# die LSP-Client-Konfiguration Ihres Editors gestartet (nicht ueber symbi repl Flags).
```

> **Hinweis:** Das `--lsp`-Flag wird bei `symbi repl` nicht unterstuetzt. LSP ist im `repl-lsp` Crate implementiert und sollte ueber die LSP-Einstellungen Ihres Editors konfiguriert werden.

### Unterstuetzte Funktionen

- Syntaxhervorhebung
- Fehlerdiagnose
- Textsynchronisation

**Geplante Funktionen** (noch nicht implementiert):
- Code-Vervollstaendigung
- Hover-Informationen
- Gehe zu Definition
- Symbolsuche

## Bewaehrte Praktiken

### Entwicklungsworkflow

1. **Mit einfachen Ausdruecken beginnen**: Grundlegende DSL-Konstrukte testen
2. **Agenten schrittweise definieren**: Mit minimalen Agentendefinitionen starten
3. **Verhalten einzeln testen**: Verhalten vor der Integration definieren und testen
4. **Ueberwachung nutzen**: Ausfuehrungsueberwachung zum Debuggen einsetzen
5. **Snapshots erstellen**: Wichtige Sitzungszustaende sichern

### Performance-Tipps

- `:monitor clear` regelmaessig verwenden, um Ueberwachungsdaten zurueckzusetzen
- Trace-Verlauf mit `:monitor traces <limit>` begrenzen
- Ungenutzte Agenten zerstoeren, um Ressourcen freizugeben
- Snapshots fuer komplexe Sitzungszustaende verwenden

### Sicherheitsueberlegungen

- Immer geeignete Capabilities fuer Agenten definieren
- Policy-Durchsetzung in der Entwicklung testen
- Sandbox-Modus fuer nicht vertrauenswuerdigen Code verwenden
- Ausfuehrungs-Traces auf Sicherheitsereignisse ueberwachen

## Fehlerbehebung

### Haeufige Probleme

**Agentenerstellung schlaegt fehl**
```
Error: Missing capability: filesystem
```
*Loesung*: Erforderliche Capabilities zum Agenten-Sicherheitsblock hinzufuegen

**Ausfuehrungs-Timeout**
```
Error: Maximum execution depth exceeded
```
*Loesung*: Auf unendliche Rekursion in der Verhaltenslogik pruefen

**Policy-Verletzung**
```
Error: Policy violation: data access denied
```
*Loesung*: Sicherstellen, dass der Agent ueber die entsprechenden Berechtigungen verfuegt

### Debug-Befehle

```rust
# Agentenstatus pruefen
:agent debug <agent-id>

# Ausfuehrungs-Traces anzeigen
:monitor traces 50

# Systemstatistiken pruefen
:monitor stats

# Debug-Snapshot erstellen
:snapshot
```

## Beispiele

### Einfacher Agent

```rust
agent Calculator {
  name: "Basic Calculator"
  version: "1.0.0"
}

behavior Add {
  input { a: number, b: number }
  output { result: number }
  steps {
    return a + b
  }
}

# Das Verhalten testen
let result = Add(5, 3)
print("5 + 3 =", result)
```

### Datenverarbeitungs-Agent

```rust
agent DataProcessor {
  name: "Data Processing Agent"
  version: "1.0.0"

  security {
    capabilities: ["data_read", "data_write"]
    sandbox: true
  }

  resources {
    memory: 256MB
    cpu: 1
  }
}

behavior ProcessCsv {
  input { file_path: string }
  output { summary: ProcessingSummary }

  steps {
    require capability("data_read")

    # HINWEIS: read_csv(), transform_data() und write_results() sind geplante
    # eingebaute Funktionen (noch nicht implementiert). Dieses Beispiel veranschaulicht
    # das beabsichtigte Muster fuer Datenverarbeitungsverhalten.
    let data = read_csv(file_path)
    let processed = transform_data(data)

    require capability("data_write")
    write_results(processed)

    return {
      "rows_processed": len(data),
      "status": "completed"
    }
  }
}
```

## Siehe auch

- [DSL-Leitfaden](dsl-guide.md) - Vollstaendige DSL-Sprachreferenz
- [Laufzeit-Architektur](runtime-architecture.md) - Systemarchitektur-Uebersicht
- [Sicherheitsmodell](security-model.md) - Sicherheitsimplementierungsdetails
- [API-Referenz](api-reference.md) - Vollstaendige API-Dokumentation
