ACP Thread Bound Agents in OpenClaw

Kennst du das? Du arbeitest mit einem Coding Agent in Discord, aber die Session-Verwaltung ist mühsam. Nachrichten gehen verloren oder der Agent verliert den Kontext, sobald die Konversation in Threads komplexer wird. Es ist nervig, wenn die Synchronisation zwischen dem Chat und dem eigentlichen Prozess abbricht oder du nach einem Neustart nicht mehr weißt, wo die Session aufgehört hat.

Diese Architektur löst das Problem, indem sie ACP Sessions direkt an Threads bindet und für eine stabile Recovery sorgt.

What You’ll Need

• OpenClaw Core: Die Basis für das Session-Management.
• Discord Integration: Ein Channel mit aktivem Thread-Support.
• ACP Runtime Backend: Ein acpx-basierter Plugin-Service.
• SQLite: Für den persistenten Control-Plane State (WAL mode).

Quick Start

In nur 5 Minuten bindest du deinen Agent an einen Thread:

1. Session starten: Nutze /focus, um eine ACP Session in einem Discord Thread zu starten oder zu fokussieren.
2. Interaktion: Sende Nachrichten direkt im Thread. OpenClaw erkennt die Bindung und leitet den Input automatisch an die richtige ACP Session weiter.
3. Streaming: Der Agent streamt seine Antworten direkt als Persona in denselben Thread zurück.
4. Lifecycle: Beende die Session explizit mit /unfocus oder durch das Archivieren des Threads.

Technische Details

OpenClaw setzt auf eine hybride Architektur. Der Core übernimmt die Kontrolle (Identity, Routing, Lifecycle), während die ACP Runtime als austauschbarer Adapter fungiert.

Jede Session durchläuft dabei diese expliziten Zustände:

• creating, idle, running
• cancelling, closed, error

Das System stellt sicher, dass Befehle idempotent ausgeführt werden. Das bedeutet für dich: Keine doppelten Runs und keine mehrfachen Discord-Outputs, selbst wenn die Verbindung kurzzeitig unterbricht.

Troubleshooting

• Doppelte Antworten bei Retries: OpenClaw nutzt Idempotency Keys. Wenn ein Befehl wiederholt wird, erkennt das System dies und verhindert doppelte Ausgaben im Discord-Thread.
• Fehlende Metadaten im Routing: Wir haben ACP Turns durch einen zentralen Core-Branch geleitet. Das schließt Lücken in den Metadaten, die früher bei reinen Plugin-Lösungen auftraten.

Hast du weitere Fragen zur Einrichtung? Nutze den AI Setup Assistant.

What’s Next

• Unified Runtime Streaming Refactor Plan

Kennst du das? Du baust eine LLM-Integration und plötzlich bricht die Verbindung ab. Der State ist weg, die Tokens sind verschwendet und du fängst von vorne an. Es ist frustrierend, wenn die Kernlogik deiner App fest mit den CLI-Details eines Backends verdrahtet ist und jede kleine Änderung das gesamte System instabil macht.

Wir wollen eine Lösung, bei der die Orchestrierung vom eigentlichen Prozess getrennt ist. Wenn der Gateway-Prozess stirbt, sollten die Sessions nicht einfach im digitalen Nirgendwo verschwinden. Hier erfährst du, wie wir das mit dem OpenClaw ACP-Modell gelöst haben.

What You’ll Need

• OpenClaw Core
• ACP SQLite Datenbank (WAL-Modus)
• Ein funktionsfähiges Plugin-Backend (acpx Implementation)
• Discord-Anbindung für das Routing

Quick Start

In nur 5 Minuten verstehst du den Pfad einer ACP-Session:

1. Backend-Wahl: Das Core-System sucht über die Registry nach einem verfügbaren AcpxRuntime Plugin.
2. Session-Initialisierung: Über /acp startest du eine Session, die im SQLite-Backend persistiert wird.
3. Process Spawning: Der Gateway-Prozess startet einen überwachten Child-Process via acpx.
4. Streaming: Events werden normalisiert und als Reply-Chunks an Discord gesendet.

Architektur

Boundary-Modell

Wir trennen strikt zwischen Core-Logik und Plugin-Backends.

Core (muss im OpenClaw Core liegen):

• ACP Session-Mode Dispatch Branch in der Reply-Pipeline.
• Delivery-Arbitrierung, um Duplikate durch Parent- und Thread-Überschneidungen zu vermeiden.
• ACP Control-Plane Persistenz (mit SessionEntry.acp Kompatibilitäts-Projektion während der Migration).
• Lifecycle-Unbind und Runtime-Detach Semantik, gekoppelt an Session-Reset oder Löschung.

Plugin-Backend (acpx Implementation):

• ACP Runtime-Worker Supervision.
• acpx Prozess-Aufruf und Event-Parsing.
• ACP Command-Handler (/acp ...) und Operator UX.
• Backend-spezifische Config-Defaults und Diagnostik.

Runtime Ownership Modell

• Ein Gateway-Prozess besitzt den ACP Orchestration-State.
• Die ACP-Ausführung läuft in überwachten Child-Prozessen über das acpx Backend.
• Die Prozess-Strategie ist langlebig pro aktivem ACP Session-Key, nicht pro Nachricht.

Das vermeidet Startup-Kosten bei jedem Prompt. Zudem bleiben Cancel- und Reconnect-Semantiken zuverlässig.

Core Runtime Contract

Wir nutzen einen Core ACP Runtime Contract. So hängt der Routing-Code nicht von CLI-Details ab und kann Backends wechseln, ohne die Dispatch-Logik zu ändern:

export type AcpRuntimePromptMode = "prompt" | "steer";

export type AcpRuntimeHandle = {
  sessionKey: string;
  backend: string;
  runtimeSessionName: string;
};

export type AcpRuntimeEvent =
  | { type: "text_delta"; stream: "output" | "thought"; text: string }
  | { type: "tool_call"; name: string; argumentsText: string }
  | { type: "done"; usage?: Record<string, number> }
  | { type: "error"; code: string; message: string; retryable?: boolean };

export interface AcpRuntime {
  ensureSession(input: {
    sessionKey: string;
    agent: string;
    mode: "persistent" | "oneshot";
    cwd?: string;
    env?: Record<string, string>;
    idempotencyKey: string;
  }): Promise<AcpRuntimeHandle>;

  submit(input: {
    handle: AcpRuntimeHandle;
    text: string;
    mode: AcpRuntimePromptMode;
    idempotencyKey: string;
  }): Promise<{ runtimeRunId: string }>;

  stream(input: {
    handle: AcpRuntimeHandle;
    runtimeRunId: string;
    onEvent: (event: AcpRuntimeEvent) => Promise<void> | void;
    signal?: AbortSignal;
  }): Promise<void>;

  cancel(input: {
    handle: AcpRuntimeHandle;
    runtimeRunId?: string;
    reason?: string;
    idempotencyKey: string;
  }): Promise<void>;

  close(input: { handle: AcpRuntimeHandle; reason: string; idempotencyKey: string }): Promise<void>;

  health?(): Promise<{ ok: boolean; details?: string }>;
}

Implementierungs-Details:

• Erstes Backend: AcpxRuntime wird als Plugin-Service ausgeliefert.
• Core löst die Runtime über die Registry auf. Wenn kein ACP Runtime-Backend verfügbar ist, gibt es einen expliziten Operator-Error.

Control-Plane Datenmodell und Persistenz

Die langfristige Source-of-Truth ist eine dedizierte ACP SQLite Datenbank (WAL-Modus). Das sorgt für transaktionale Updates und Recovery nach Abstürzen:

• acp_sessions: session_key (pk), backend, agent, mode, cwd, state, created_at, updated_at, last_error
• acp_runs: run_id (pk), session_key (fk), state, requester_message_id, idempotency_key, started_at, ended_at, error_code, error_message
• acp_bindings: binding_key (pk), thread_id, channel_id, account_id, session_key (fk), expires_at, bound_at
• acp_events: event_id (pk), run_id (fk), seq, kind, payload_json, created_at
• acp_delivery_checkpoint: run_id (pk/fk), last_event_seq, last_discord_message_id, updated_at
• acp_idempotency: scope, idempotency_key, result_json, created_at, unique (scope, idempotency_key)

export type AcpSessionMeta = {
  backend: string;
  agent: string;
  runtimeSessionName: string;
  mode: "persistent" | "oneshot";
  cwd?: string;
  state: "idle" | "running" | "error";
  lastActivityAt: number;
  lastError?: string;
};

Speicher-Regeln:

• SessionEntry.acp bleibt als Kompatibilitäts-Projektion erhalten.
• Prozess-IDs und Sockets leben nur im Memory.
• Lifecycle und Run-Status liegen in der ACP DB, nicht im generischen Session-JSON.
• Wenn der Runtime-Owner stirbt, rehydriert das Gateway aus der ACP DB und setzt bei den Checkpoints fort.

Routing und Delivery

Inbound:

• Der Thread-Binding-Lookup ist der erste Routing-Schritt.
• Wenn das Ziel eine ACP-Session ist, wird zum ACP Runtime-Branch geroutet statt zu getReplyFromConfig.
• Der Befehl /acp steer nutzt explizit mode: "steer".

Outbound:

• Der ACP Event-Stream wird in OpenClaw Reply-Chunks normalisiert.
• Das Delivery-Target wird über den bestehenden Bound Destination Path aufgelöst.
• Wenn ein Thread für diesen Session-Turn aktiv ist, wird die Parent-Channel-Completion unterdrückt.

Streaming-Policy:

• Partieller Output wird mit einem Coalescing-Window gestreamt.
• Es gibt konfigurierbare Intervalle und Max-Chunk-Bytes für Discord Rate-Limits.
• Die finale Nachricht wird immer bei Abschluss oder Fehler gesendet.

State Machines und Transaktions-Grenzen

Session State Machine:

• creating -> idle -> running -> idle
• running -> cancelling -> idle | error
• idle -> closed
• error -> idle | closed

Run State Machine:

• queued -> running -> completed
• running -> failed
• running -> cancelled
• queued -> cancelled

Transaktions-Grenzen:

• Spawn-Transaktion: Erstellt ACP-Session-Row, erstellt/aktualisiert Thread-Binding, reiht initialen Run ein.
• Close-Transaktion: Markiert Session als geschlossen, löscht/entwertet Bindings, schreibt finalen Close-Event.
• Cancel-Transaktion: Markiert Run als cancelling/cancelled mit Idempotency-Key.

Partielle Erfolge sind innerhalb dieser Grenzen nicht erlaubt.

Per-Session Actor Modell

Der AcpSessionManager führt einen Actor pro ACP Session-Key aus:

• Die Actor Mailbox serialisiert submit, cancel, close und stream Side-Effects.
• Der Actor besitzt die Runtime-Handle-Hydrierung und den Lifecycle des Adapter-Prozesses.
• Events werden in der richtigen Reihenfolge (seq) geschrieben, bevor sie an Discord gehen.
• Delivery-Checkpoints werden nach erfolgreichem Senden aktualisiert.

Das verhindert Race-Conditions zwischen Turns und verhindert doppelten oder falschen Thread-Output.

Idempotenz und Delivery-Projektion

Alle externen ACP-Aktionen brauchen Idempotency-Keys:

• Spawn Idempotency-Key
• Prompt/Steer Idempotency-Key
• Cancel Idempotency-Key
• Close Idempotency-Key

Delivery-Regeln:

• Discord-Nachrichten leiten sich aus acp_events und acp_delivery_checkpoint ab.
• Retries setzen am Checkpoint an, ohne bereits gesendete Chunks erneut zu schicken.
• Die finale Antwort wird genau einmal (exactly-once) gesendet.

Recovery und Self-healing

Beim Gateway-Start:

• Lädt nicht-terminale Sessions (creating, idle, running, cancelling, error).
• Erstellt Actoren verzögert beim ersten Event oder sofort bei konfiguriertem Cap.
• Prüft running Runs ohne Heartbeat und markiert sie als failed oder stellt sie wieder her.

Bei Inbound Discord Thread-Messages:

• Wenn ein Binding existiert, aber die Session fehlt, bricht das System mit einer Fehlermeldung ab.
• Veraltete Bindings können nach Validierung automatisch gelöscht werden.
• Stale ACP-Bindings werden niemals stillschweigend an den normalen LLM-Pfad geroutet.

Lifecycle und Sicherheit

Unterstützte Operationen:

• Aktuellen Run abbrechen: /acp cancel
• Thread-Binding lösen: /unfocus
• Session schließen: /acp close
• Inaktive Sessions automatisch schließen (TTL).

TTL-Policy: Die effektive TTL ist das Minimum aus Global/Session TTL, Discord Thread Binding TTL und ACP Runtime Owner TTL.

Sicherheits-Controls:

• Allowlist für ACP-Agenten nach Name.
• Eingeschränkte Workspace-Roots für Sessions.
• Env-Allowlist Passthrough.
• Max concurrent Sessions pro Account und global.
• Bounded Restart-Backoff bei Prozess-Crashs.

Troubleshooting

• Stale Bindings: Wenn eine Session in der Datenbank fehlt, aber das Binding noch aktiv ist, nutze /unfocus.
• Runtime Crashes: Das System nutzt einen Restart-Backoff. Prüfe die last_error Spalte in acp_sessions für Details.
• Rate Limits: Wenn Discord-Nachrichten hängen, prüfe die Konfiguration für min interval und max chunk bytes.

Hast du Fragen zur Implementierung? Frag unseren AI Setup Assistant.

What’s Next

• Plugin Guide
• CLI Reference
• Session Management

Kennst du das? Du willst eigentlich nur deine Agenten zum Laufen bringen, aber die halbe Zeit geht dafür drauf, die richtigen Schalter in der Konfiguration zu finden. Es ist oft frustrierend, wenn man raten muss, welcher Key für welches Verhalten zuständig ist, anstatt einfach loszulegen.

Eine klare Struktur in der Konfiguration hilft dir dabei, den Fokus auf die eigentliche Entwicklung zu legen. Wenn du weißt, wo du drehen musst, um das Routing zu kappen oder die Session-Dauer zu begrenzen, sparst du dir eine Menge Debugging-Zeit.

What You’ll Need

• Zugriff auf deine Konfigurationsdatei (z. B. YAML oder JSON).
• Eine aktive Instanz, in der du die Keys setzen kannst.

Quick Start

In fünf Minuten hast du die Basis für dein ACP (Agent Control Plane) stehen. Folge diesen Schritten:

1. ACP aktivieren: Setze acp.enabled auf true.
2. Backend wählen: Bestimme dein Backend mit acp.backend (Standard ist acpx).
3. Limits definieren: Lege mit acp.maxConcurrentSessions fest, wie viele Sessions gleichzeitig laufen dürfen.
4. Speicherort festlegen: Konfiguriere acp.controlPlane.storePath, damit deine Daten sicher landen.

Core Keys

Hier sind die zentralen Stellschrauben für dein System:

• acp.enabled: Aktiviert oder deaktiviert ACP.
• acp.dispatch.enabled: Ein unabhängiger Kill-Switch für das ACP Routing.
• acp.backend: Das genutzte Backend (Standard: acpx).
• acp.defaultAgent: Legt fest, welcher Agent standardmäßig genutzt wird.
• acp.allowedAgents[]: Eine Liste der zugelassenen Agenten.
• acp.maxConcurrentSessions: Maximale Anzahl gleichzeitiger Sessions.
• acp.stream.coalesceIdleMs: Zeitspanne für das Zusammenführen von Streams im Leerlauf.
• acp.stream.maxChunkChars: Maximale Zeichenanzahl pro Chunk im Stream.
• acp.runtime.ttlMinutes: Time-to-Live für die Runtime in Minuten.
• acp.controlPlane.store: Speicher-Typ (Standard: sqlite).
• acp.controlPlane.storePath: Dateipfad zum Speicher der Control Plane.
• acp.controlPlane.recovery.eagerActors: Steuert die sofortige Wiederherstellung von Actors.
• acp.controlPlane.recovery.reconcileRunningAfterMs: Zeitintervall für den Abgleich laufender Prozesse.
• acp.controlPlane.checkpoint.flushEveryEvents: Checkpoint-Erstellung nach einer bestimmten Anzahl von Events.
• acp.controlPlane.checkpoint.flushEveryMs: Zeitbasiertes Schreiben von Checkpoints.
• acp.idempotency.ttlHours: Gültigkeitsdauer von Idempotency-Keys in Stunden.
• channels.discord.threadBindings.spawnAcpSessions: Erlaubt das Starten von ACP Sessions über Discord-Threads.

Plugin/Backend Keys (acpx)

Wenn du das acpx Plugin verwendest, stehen dir folgende Optionen zur Verfügung:

• Backend Command/Path Overrides: Überschreibe die Standardpfade und Befehle des Backends.
• Backend Env Allowlist: Definiere, welche Umgebungsvariablen an das Backend durchgereicht werden.
• Backend Per-Agent Presets: Spezifische Einstellungen für einzelne Agenten.
• Backend Startup/Stop Timeouts: Zeitlimits für das Starten und Stoppen des Backends.
• Backend Max Inflight Runs Per Session: Begrenzt die Anzahl der parallel laufenden Prozesse pro Session.

Brauchst du Hilfe bei der Einrichtung? Frag den AI Setup Assistant.

What’s Next

• Backend Configuration Guide
• Managing Agent Sessions

---
title: "ACP Implementierung: So baust du die neue Control-Plane"
description: "Ein tiefer Einblick in die technische Spezifikation der ACP Control-Plane, von der Registry-API bis zum acpx-Runtime-Contract."
---

Kennst du das Problem? Du versuchst, Agent-Sessions über verschiedene Runtimes hinweg stabil zu halten, aber die Zustände laufen ständig auseinander. Manchmal verliert man den Überblick über die Actor-Lifecycles oder Befehle kommen doppelt an, was das ganze System instabil macht.

Genau hier setzt die neue ACP (Agent Control Plane) Architektur an. Wir führen eine dedizierte Control-Plane ein, die Ordnung in das Chaos bringt und sicherstellt, dass Sessions atomar, idempotent und nachvollziehbar ablaufen.

## What You'll Need

Bevor du startest, solltest du sicherstellen, dass du Zugriff auf folgende Core-Bereiche hast:
- Das `src/acp` Verzeichnis für die neuen Control-Plane Module.
- Eine SQLite-Umgebung für das `store.ts` Management.
- Zugriff auf die `src/config/sessions/types.ts`, um das Session-Schema zu erweitern.

## Quick Start: In 5 Minuten zur ersten ACP-Session

Um ein Backend zu registrieren und die Control-Plane zu nutzen, folgst du diesem Pfad:

1. **Backend registrieren**: Implementiere das `AcpRuntimeBackend` Interface und nutze `registerAcpRuntimeBackend`.
2. **Session initialisieren**: Rufe `AcpSessionManager.submit` auf. Dies sorgt für eine atomare Bindung zwischen Session und Thread.
3. **Befehle senden**: Nutze die standardisierten CLI-Flags für `acpx`, um Sessions zu steuern.
4. **Events konsumieren**: Verarbeite die ndjson-Events (text, thought, tool_call), die direkt von der Runtime kommen.

## Die Control-Plane Module

Wir haben den Core um dedizierte ACP-Module erweitert, um die Logik sauber zu trennen:

*   `src/acp/control-plane/manager.ts`: Verwaltet ACP-Actors, Lifecycle-Übergänge und Befehls-Serialisierung.
*   `src/acp/control-plane/store.ts`: SQLite Schema-Management, Transaktionen und Query-Helper.
*   `src/acp/control-plane/events.ts`: Typisierte ACP-Event-Definitionen.
*   `src/acp/control-plane/checkpoint.ts`: Checkpoints für garantierte Zustellung und Replay-Cursor.
*   `src/acp/control-plane/idempotency.ts`: Reservierung von Idempotency-Keys.
*   `src/acp/control-plane/recovery.ts`: Reconciliation beim Booten und Rehydrierung von Actors.

Zusätzlich gibt es `src/acp/runtime/session-meta.ts` als temporäre Bridge für die Projektion in `SessionEntry.acp`.

## Wichtige Invarianten

Diese Regeln musst du im Code erzwingen:
- ACP-Session-Erstellung und Thread-Bindung sind atomar (eine einzige Transaktion).
- Es darf maximal ein aktiver Run pro ACP-Session-Actor gleichzeitig existieren.
- Die Event-`seq` muss pro Run strikt ansteigen.
- Delivery-Checkpoints dürfen niemals weiter fortgeschritten sein als das letzte committete Event.
- Idempotency-Replays geben bei doppelten Keys das vorherige Erfolgs-Payload zurück.

## ACP Runtime Registry API

Das Herzstück für die Backend-Verwaltung ist das neue Registry-Modul in `src/acp/runtime/registry.ts`.

```ts
Export type AcpRuntimeBackend = {
  id: string;
  runtime: AcpRuntime;
  healthy?: () => boolean;
};

export function registerAcpRuntimeBackend(backend: AcpRuntimeBackend): void;
export function unregisterAcpRuntimeBackend(id: string): void;
export function getAcpRuntimeBackend(id?: string): AcpRuntimeBackend | null;
export function requireAcpRuntimeBackend(id?: string): AcpRuntimeBackend;

requireAcpRuntimeBackend wirft einen Fehler, wenn das Backend fehlt. Plugins registrieren ihr Backend beim start und entfernen es beim stop.

Der acpx Runtime Plugin Contract

Für das acpx Backend nutzen wir einen strikten Contract. Die runtimeSessionName wird als acpx:v1:<base64url(json)> kodiert und enthält Felder wie name, agent, cwd und mode.

Command Mapping

Die Steuerung erfolgt über spezifische CLI-Befehle:

• Session sicherstellen: acpx --format json --json-strict --cwd <cwd> <agent> sessions ensure --name <name>
• Prompt senden: acpx --format json --json-strict --cwd <cwd> <agent> prompt --session <name> --file -
• Abbrechen: acpx --format json --json-strict --cwd <cwd> <agent> cancel --session <name>
• Schließen: acpx --format json --json-strict --cwd <cwd> <agent> sessions close <name>

Streaming

Events werden als ndjson konsumiert:

• text wird zu text_delta/output
• thought wird zu text_delta/thought
• tool_call, done und error werden direkt gemappt.

Session Schema & Migration

Das SessionEntry in src/config/sessions/types.ts bekommt ein Update:

type SessionAcpMeta = {
  backend: string;
  agent: string;
  runtimeSessionName: string;
  mode: "persistent" | "oneshot";
  cwd?: string;
  state: "idle" | "running" | "error";
  lastActivityAt: number;
  lastError?: string;
};

Das Feld SessionEntry.acp?: SessionAcpMeta wird persistiert. Die Migration erfolgt in vier Phasen:

1. Phase A: Dual-Write (Projektion + SQLite).
2. Phase B: Read-Primary von SQLite mit Fallback auf Legacy-Daten.
3. Phase C: Backfill-Migration für fehlende SQLite-Rows.
4. Phase D: Entfernen des Fallback-Reads.

Duplicate Delivery Arbitration

Für ACP-gebundene Turns gilt eine klare Regel: Wenn ein aktives Thread-Binding existiert, wird nur an diesen Thread geliefert. Es erfolgt keine parallele Zustellung an den Parent-Channel. Falls die Zielwahl unklar ist, bricht das System mit einem Fehler ab (Fail-Closed), statt blind auf den Parent-Channel auszuweichen.

Rollout & Kill Switch

Sicherheit geht vor. Wir führen einen Kill-Switch ein: acp.dispatch.enabled. In der ersten Version ist dieser standardmäßig auf false. Wenn er deaktiviert ist, können Sessions zwar gebunden, aber der ACP-Dispatch-Pfad nicht aktiviert werden. Nutzer erhalten dann eine Nachricht, dass der Dispatch per Policy deaktiviert ist.

Troubleshooting

Hier sind die häufigsten Fehlercodes aus der Source:

• ACP_BACKEND_MISSING: Das Runtime-Backend ist nicht konfiguriert. Du musst das acpx Plugin installieren und aktivieren.
• ACP_BACKEND_UNAVAILABLE: Das Backend ist gerade nicht erreichbar. Versuche es gleich noch einmal.
• ACP_SESSION_INIT_FAILED: Die Session-Runtime konnte nicht initialisiert werden.
• ACP_TURN_FAILED: Der Turn wurde vor Abschluss abgebrochen.

What’s Next

• Schau dir die src/acp/runtime/registry.test.ts für Unit-Tests an.
• Prüfe die src/discord/monitor/reply-delivery.test.ts für das Routing-Verhalten.
• Erfahre mehr über das Session Lifecycle Management.

Hast du Fragen zur Einrichtung? Unser AI Setup Assistant hilft dir gerne weiter.

Kennst du das? Du baust komplexe Agenten-Workflows, aber die Kontrolle über Sessions, Threads und Zustände fühlt sich an wie ein Ratespiel. Manchmal hängen Prozesse fest, oder die Zuordnung zwischen User-Input und Agenten-Output geht im Chaos verloren, weil ein klarer Control-Plane-Layer fehlt.

Wir lösen dieses Problem mit dem neuen Agent Control Plane (ACP) Plan. Ziel ist es, eine robuste Basis für die Steuerung von Agenten zu schaffen, die sowohl über CLI als auch über automatische Routings präzise funktioniert.

## What You'll Need

- Zugriff auf die Core-Control-Plane-Module und Tests.
- Eine funktionierende Discord-Integration (für die erste Phase der Channel-Projection).
- SQLite für den persistenten Store.
- Ein konfiguriertes `acpx` Backend.

## Quick Start

In weniger als 5 Minuten kannst du die neuen ACP-Befehle verwenden, um Agenten-Sessions zu verwalten. Hier ist der minimale Pfad:

1.  **Agenten starten:**
    Erstelle eine neue Session mit einem spezifischen Modus und Thread-Verhalten.
    `/acp spawn <agent-id> --mode persistent --thread auto`

2.  **Anweisungen senden:**
    Steuere den Agenten direkt innerhalb der aktiven Session.
    `/acp steer "Analysiere die Log-Dateien nach Fehlern"`

3.  **Status prüfen:**
    Sieh dir alle aktiven Sessions an, um den Überblick zu behalten.
    `/acp sessions`

4.  **Session beenden:**
    Schließe die Session sauber ab, wenn die Aufgabe erledigt ist.
    `/acp close`

## Der Command & UX Plan

Wir führen eine Reihe neuer Befehle ein und behalten gleichzeitig die Kompatibilität mit bestehenden Systemen bei.

### Neue Befehle

- `/acp spawn <agent-id> [--mode persistent|oneshot] [--thread auto|here|off]`
- `/acp cancel [session]`
- `/acp steer <instruction>`
- `/acp close [session]`
- `/acp sessions`

### Kompatibilität bestehender Befehle

- `/focus <sessionKey>` unterstützt weiterhin ACP-Targets.
- `/unfocus` behält die aktuelle Semantik bei.
- `/session idle` und `/session max-age` ersetzen das alte TTL-Override-System.

## Phasen des Rollouts

Der Rollout erfolgt in sechs Phasen, um Stabilität und Datenintegrität zu gewährleisten.

### Phase 0: ADR und Schema Freeze
- Veröffentlichung des ADR für ACP Control-Plane Ownership und Adapter-Grenzen.
- Freeze des DB-Schemas (`acp_sessions`, `acp_runs`, `acp_bindings`, `acp_events`, `acp_delivery_checkpoint`, `acp_idempotency`).
- Definition stabiler ACP Error-Codes, Event-Contracts und State-Transition Guards.

### Phase 1: Control-Plane Foundation im Core
- Implementierung des `AcpSessionManager` und Per-Session Actor-Runtime.
- Implementierung des ACP SQLite Store und Transaction-Helpers.
- Implementierung des Idempotency Store und Replay-Helpers.
- Implementierung der Event-Append + Delivery Checkpoint Module.
- Anbindung der Spawn/Cancel/Close APIs an den Manager mit transaktionalen Garantien.

### Phase 2: Core Routing und Lifecycle Integration
- Routing von Thread-bound ACP Turns aus der Dispatch-Pipeline in den ACP Manager.
- Erzwingen von Fail-closed Routing, wenn ACP Binding/Session Invarianten fehlschlagen.
- Integration von Reset/Delete/Archive/Unfocus Lifecycle mit ACP Close/Unbind Transaktionen.
- Implementierung von Stale-Binding Detection und optionaler Auto-Unbind Policy.

### Phase 3: acpx Backend Adapter/Plugin
- Implementierung des `acpx` Adapters gegen den Runtime-Contract (`ensureSession`, `submit`, `stream`, `cancel`, `close`).
- Backend Health-Checks und Startup/Teardown Registrierung.
- Normalisierung von `acpx` ndjson Events in ACP Runtime Events.
- Durchsetzung von Backend-Timeouts, Process Supervision und Restart/Backoff Policies.

### Phase 4: Delivery Projection und Channel UX (Discord zuerst)
- Implementierung der Event-driven Channel Projection mit Checkpoint Resume (Discord zuerst).
- Coalescing von Streaming-Chunks mit Rate-limit aware Flush Policy.
- Garantie einer Exactly-once Final Completion Message pro Run.
- Release der Befehle `/acp spawn`, `/acp cancel`, `/acp steer`, `/acp close`, `/acp sessions`.

### Phase 5: Migration und Cutover
- Einführung von Dual-write in die `SessionEntry.acp` Projection plus ACP SQLite Source-of-Truth.
- Migration-Utility für Legacy ACP Metadaten-Rows.
- Umstellung des Read-Paths auf ACP SQLite als Primary.
- Entfernung des Legacy Fallback-Routings.

### Phase 6: Hardening, SLOs und Scale Limits
- Durchsetzung von Concurrency Limits (Global/Account/Session), Queue-Policies und Timeout-Budgets.
- Komplette Telemetrie, Dashboards und Alert-Thresholds.
- Chaos-Testing für Crash-Recovery und Duplicate-Delivery Suppression.
- Veröffentlichung des Runbooks für Backend-Ausfälle und DB-Corruption.

## Test Plan

### Unit Tests
- ACP DB Transaktionsgrenzen (Spawn/Bind/Enqueue Atomizität, Cancel, Close).
- ACP State-Machine Transition Guards für Sessions und Runs.
- Idempotency Reservierung/Replay Semantik über alle ACP Befehle.
- Per-Session Actor Serialisierung und Queue-Ordering.
- acpx Event-Parser und Chunk-Coalescer.
- Runtime Supervisor Restart und Backoff Policy.
- Config-Präzedenz und effektive TTL-Berechnung.
- Core ACP Routing Branch-Selektion und Fail-closed Verhalten.

### Integration Tests
- Fake ACP Adapter Prozess für deterministisches Streaming und Cancel-Verhalten.
- ACP Manager + Dispatch Integration mit transaktionaler Persistenz.
- Thread-bound Inbound Routing zum ACP Session Key.
- Checkpoint Replay stellt nach Delivery-Fehlern den Zustand wieder her.

### Gateway e2e Tests
- Spawn ACP mit Thread, Austausch von Multi-turn Prompts, Unfocus.
- Gateway Restart mit persistierter ACP DB und Bindings, danach Fortsetzung der Session.
- Keine Cross-talk Effekte bei concurrent ACP Sessions in mehreren Threads.
- Duplicate Command Retries erzeugen keine doppelten Runs.

## Troubleshooting

Hier sind Lösungen für bekannte Probleme aus der Entwicklung:

- **Problem:** Doppelte Deliveries während der Transition.
  - **Lösung:** Wir verwenden einen Single Destination Resolver und einen idempotent Event Checkpoint.
- **Problem:** Runtime Process Churn unter hoher Last.
  - **Lösung:** Nutzung von Long-lived Per-Session Owners kombiniert mit Concurrency Caps und Backoff-Strategien.
- **Problem:** Plugin fehlt oder ist falsch konfiguriert.
  - **Lösung:** Das System nutzt explizite Fehlermeldungen für Operatoren und Fail-closed ACP Routing (kein impliziter Fallback).
- **Problem:** Konfigurations-Konflikte zwischen Subagent und ACP Gates.
  - **Lösung:** Explizite ACP Keys und Command-Feedback, das die effektive Policy-Quelle anzeigt.

## Addendum: Refactors

Diese Refactors wurden bereits abgeschlossen, um die Wartbarkeit zu erhöhen:

### 1. Zentralisierung der ACP Dispatch Policy
Implementiert in `src/acp/policy.ts`. Dispatch und Lifecycle-Handler nutzen nun diese geteilte Logik.

### 2. Splitting der ACP Command Handler
`src/auto-reply/reply/commands-acp.ts` ist jetzt ein schlanker Router. Die Logik ist aufgeteilt in:
- `src/auto-reply/reply/commands-acp/lifecycle.ts`
- `src/auto-reply/reply/commands-acp/runtime-options.ts`
- `src/auto-reply/reply/commands-acp/diagnostics.ts`

### 3. Splitting des ACP Session Manager
Der Manager wurde in vier Bereiche unterteilt:
- `src/acp/control-plane/manager.ts` (Public Facade)
- `src/acp/control-plane/manager.core.ts` (Implementierung)
- `src/acp/control-plane/manager.types.ts` (Typen)
- `src/acp/control-plane/manager.utils.ts` (Helper)

Du hast Fragen zum Setup oder brauchst Hilfe bei der Integration? Unser [AI Setup Assistant](/docs/#docs-chat) unterstützt dich dabei.

**What's Next:**
- [ACP SQLite Schema Dokumentation](/docs/#docs-db)
- [Discord Adapter Konfiguration](/docs/#docs-discord)
- [acpx Runtime Specification](/docs/#docs-acpx)