ki-grok/11-acp-ide-integration-und-bots.md

Kapitel 11

ACP, IDE-Integration und Bots

Kern in einem Satz: ACP macht Grok zum langlebigen Agent-Server (JSON-RPC): IDEs und eigene Clients steuern Sessions – dieselbe Engine wie TUI/Headless, andere Lebensdauer und Transport.

---

11.1 Headless vs. Agent Mode

	Headless grok -p	Agent grok agent …
Lebensdauer	ein Prompt, dann Exit	Prozess bleibt / reconnect
Transport	CLI stdout	stdio, WebSocket serve, Relay
Typische Clients	Scripts, CI	IDEs, SDKs, Bots
Permissions	immer non-interaktiv denken	interaktiv möglich, oft YOLO

Merksatz: Einmal-Job → -p. Editor/Bot mit mehreren Turns → agent.

---

11.2 Was ACP abdeckt

Agent Client Protocol über JSON-RPC:

• Sessions erzeugen, laden, fortsetzen
• Prompts und gestreamte Antworten
• Tool-Call-Updates
• Reasoning/Thought-Streams
• Permission-Requests (wenn nicht always-approve)

Architektur skizziert:

IDE / SDK / Bot
      │  JSON-RPC (stdio oder WS)
      ▼
grok agent
  Session Manager · Tools · MCP

---

11.3 stdio – der lokale Standardweg

grok agent --always-approve stdio
grok agent --always-approve --model grok-build stdio

Flags nach agent und vor dem Mode-Namen; mode-spezifische Flags danach (serve --bind …).

Flag	Bedeutung
-m / --model	Modell
--always-approve / --yolo	ohne Permission-UI
--reauth	Auth vor Start
--agent-profile <PATH>	Profil-Datei
--leader / --no-leader	shared Leader vs. lokal

Clients: ACP-fähige IDEs/Editoren (z. B. Zed, Neovim, Emacs-Integrationen), Custom-Tools, SDKs. Konkrete Marketplace-Extensions ändern sich – Konzept bleibt: Client startet grok agent … stdio und spricht ACP.

Transport-Fokus: stdio ist der lokale Standard (Client startet den Prozess). Härtung (Always-approve + Deny + Sandbox) bündelst du in 11.8 und Kapitel 13 – hier nur der Startweg.

Session-seitig YOLO (Client-Meta, Implementierung abhängig):

{
  "cwd": "/path/to/project",
  "mcpServers": [],
  "_meta": { "yoloMode": true }
}

---

11.4 Server Mode (WebSocket)

grok agent --always-approve serve \
  --bind 127.0.0.1:2419 \
  --secret YOUR_TOKEN

• Client verbindet per WebSocket, auth mit Secret.
• Ohne --secret: generierter Token beim Start, oder Env GROK_AGENT_SECRET.
• State überlebt Client-Reconnects.

Achtung: --bind 0.0.0.0 ohne Netz-Härtung ist ein offener Agent mit Tool-Rechten. Default: localhost. Secret wie ein API-Key behandeln. Reverse-Proxy + TLS, wenn remote.

---

11.5 Relay / Headless-Agent über WebSocket

grok agent --always-approve headless \
  --grok-ws-url wss://your-relay.example.com/ws

Für Browser/Remote-Clients über gemeinsamen Relay – Ops-Thema (Auth, Allowlists, Logging). Nicht „mal eben öffentlich“.

---

11.6 Session-Lifecycle (Protokoll-Basics)

1. initialize – Capabilities
2. session/new – CWD, optionale MCP-Liste, Meta (yolo, …)
3. session/prompt – User-Messages
4. session/update – Stream (Text, Tools, Thoughts)
5. Permissions – Approve/Deny oder Mode-Policy

Als Nutzer siehst du das in der IDE als Chat + Diffs. Als Integrationsbauer loggst du JSON-RPC (Permissions, CWD, Tool-Calls) – sonst debuggst du „hängt“ und „falscher Tree“ blind. Teste mit always-approve + Deny.

ACP-Extensions (Auszug aus Guide): u. a. Git-Worktree-Methoden (x.ai/git/worktree/*), Session-Helpers – nützlich für isolierte IDE-Sessions (Kapitel 6).

---

11.7 IDE-Alltag: was gleich bleibt

Alltagsschmerz: Falscher CWD, Diff akzeptiert ohne Lesen, Always-approve „weil die IDE fragt nervt“. Unabhängig vom Editor-Skin gelten dieselben Steuerknöpfe:

Thema	In der IDE genauso wichtig
CWD / geöffnetes Projekt	falscher Tree = falsche Edits
AGENTS.md	wird geladen wie in der TUI
Plan Mode	wo die Integration ihn exposed
Diff-Review	nie blind Accept
MCP/Hooks	Trust-Folder, Plugin-Trust
Always-approve	nur mit Deny/Sandbox

Lernpfad: Konzepte in der TUI lernen (Kapitel 2–9), IDE als Surface dazunehmen – nicht umgekehrt.

---

11.8 Bots und langlebige Worker

Typische Muster:

1. PR-Bot: Webhook → Worker startet grok -p (einfach) oder hält agent serve (komplex, multi-turn).
2. Eval-Harness: ACP stdio, feste Prompts, JSON-Metriken.
3. Pair-Bot: serve auf localhost, UI im Intranet.

# Eval-Skizze: stdio-Client steuert Turns
# Harte Limits: [permission] deny in .grok/config.toml (agent-CLI listet --deny nicht)
grok agent --always-approve stdio

# .grok/config.toml (Bot-Worker)
[permission]
deny = [
  "Bash(rm -rf *)",
  "Bash(git push --force *)",
  "Bash(git push -f *)",
]

Hardening-Checkliste für Bots:

• Secret/API-Key nur Env
• Always-approve + Deny (Config/Hooks) + ideal Sandbox
• Bind localhost oder mTLS
• max cost/turns clientseitig
• Audit-Log der Prompts (ohne Secrets)
• Least-privilege Repo-Token (read vs. write)

---

11.9 Praxis-Sessions

Session 1 – stdio smoke (lokal)

# Terminal A
grok agent --always-approve stdio
# Terminal B / Client: initialize + session/new + kurzer Prompt
# (SDK oder minimaler JSON-RPC-Client)

Ohne eigenen Client: IDE-Extension mit Grok-ACP verbinden und einen Read-only-Prompt senden.

Session 2 – serve + Secret

export GROK_AGENT_SECRET="dev-only-change-me"   # nur lokal/Env – nicht committen
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret "$GROK_AGENT_SECRET"

Mit WS-Client connecten; falsches Secret muss scheitern.

Session 3 – IDE Diff-Disziplin

In der IDE: kleiner Edit-Auftrag → Diff im Editor reviewen → Accept/Reject bewusst. Vergleiche mit TUI-Scrollback-Diff (Kapitel 3).

Session 4 – YOLO vs. ask im Agent

Einmal ohne --always-approve (wenn Client Permissions supported): Permission-UI erscheint.
Dann mit YOLO + Deny: spüre den Unterschied für Automation.

Session 5 – Bot-Policy skizzieren

Entwirf eine Policy für einen PR-Review-Bot:
erlaubte Tools, Deny-Liste, max-turns, ob -p oder agent serve,
welche GitHub permissions. Noch kein Code.

---

11.10 Jetzt selbst machen: ACP-Parcours (20 Minuten)

Jetzt selbst machen

1. grok agent --help / Mode-Hilfe lesen.
2. stdio oder serve einmal starten und sauber beenden.
3. Secret-Handling notieren (Env vs. Flag).
4. In deiner IDE: ob/wie Grok/ACP angebunden ist – einen Read-only-Turn.
5. Diff accept nach Lesen.
6. Bot vs. Headless: eine Tabelle „wann was“ für dein Team skizzieren.

---

11.11 Häufige Fehler

Symptom	Ursache	Fix
Client hängt auf Permissions	kein YOLO, kein UI	--always-approve + Deny
Connection refused	falscher Bind/Port	127.0.0.1, Port prüfen
Unauthorized	Secret mismatch	GROK_AGENT_SECRET
Agent schreibt im falschen Repo	cwd in session/new	CWD explizit setzen
Öffentlich erreichbar	0.0.0.0 ohne Schutz	localhost / VPN / Auth

---

11.12 Checkliste

• Transport gewählt (stdio vs. serve)
• Always-approve nur mit Gates
• Secret und Bind gehärtet
• CWD/Trust korrekt
• Diff-Review-Prozess in der IDE
• Bot least privilege

---

Was du jetzt kannst

• ACP von Headless unterscheiden und stdio/serve starten
• IDE- und Bot-Integrationen mit denselben Safety-Hebeln absichern
• Einen minimalen Lifecycle (initialize → session → prompt) erklären

Nächste Schritte

→ Kapitel 12 – Memory, Sessions und Kontextmanagement: was auf Disk liegt, wie du resumest, compactest und Memory bewusst einsetzt.