Befehls-API (CIP)

Die Befehls-API (/api/commands) ist der clientseitige Vertrag des Command-Interaction-Protocol (CIP) von SupaCloud. Sie stellt denselben typisierten Befehlssatz bereit, den das Web-Terminal und die Telegram-/Discord-Bots nutzen — so kann eine neue Oberfläche (ein Bot, eine CLI, ein mobiler oder Sprach-Client) SupaCloud-Befehle ausführen, ohne Parsing, Optionslisten oder Validierung neu zu implementieren. Registry, Optionsanbieter und die Auflösungs-Zustandsmaschine leben einmalig im Server (server/src/services/command_registry/); diese API ist ein dünner Vertrag darüber (ADR 0049 §2.2).

Hinweis

Die Authentifizierung ist die übliche Browser-Sitzung (das Cookie supacloud_session). Jeder Endpunkt löst den aktiven Workspace auf (Header X-Workspace-Id, sonst dein Standard-Workspace) sowie deine Workspace-Rolle und filtert den Katalog dann auf die Befehle, die du tatsächlich ausführen darfst. Der Vertrag listet, löst oder führt niemals einen Befehl aus, den deine Rolle nicht ausführen darf — ein unbekanntes oder rollenbedingt verstecktes Befehlswort ergibt einen 404, keinen 403.

Endpunkte

Methode	Pfad	Zweck
GET	/api/commands	Die für den Aufrufer verfügbaren Befehlsdeskriptoren auflisten.
GET	/api/commands/options/{provider_id}?q=	Die Auswahl eines benannten Optionsanbieters auflösen, gefiltert per q.
POST	/api/commands/{word}/resolve	Den Resolver weiterführen: ready | need_param | invalid.
POST	/api/commands/{word}/invoke	Auflösen und — wenn bereit — die gerenderte Antwort zurückgeben.

GET /api/commands

Liefert das Array der Deskriptoren der Befehle, die der Aufrufer ausführen darf. Jeder Deskriptor enthält:

• word und aliases — das kanonische Wort plus Alternativen (z. B. f → follow).
• category — der Entdeckungs-Bereich (control, tasks, resources, admin).
• description_i18n — ein i18n-Schlüssel, den du in deine eigene Sprache auflöst.
• scope — task | project | workspace | global.
• surfaces — wo der Befehl angeboten wird (enthält hier immer api).
• params — die geordneten, typisierten Parameter (name, description_i18n, required, kind, options).

Der kind eines Parameters ist enum, ref (mit ref_kind wie task/project/model), free_text, int_range (mit min/max) oder attachment. Sein options ist static (eine geschlossene Werteliste), dynamic (über einen benannten Anbieter aufgelöst) oder none.

GET /api/commands/options/{provider_id}

Löst die Live-Auswahlliste eines dynamic-Parameters gegen deine Mandanten auf. Anbieter-IDs sind u. a. recent_tasks, models, efforts, projects und agents. Die optionale Abfrage q ist ein Teilstring-Filter ohne Groß-/Kleinschreibung (leer = die vollständige, begrenzte Liste). Eine nicht registrierte Anbieter-ID ergibt 404.

Jede Choice ist { value, label, hint?, glyph? } — value ist der Wert, den du in eine Ausführung bindest; label ist der Anzeigetext.

POST /api/commands/{word}/resolve

Body: { "args": { "<param>": "<wert>", … } } (args für eine parameterlose Ausführung weglassen). Der Antwort-status ist einer von:

• ready — jeder erforderliche Parameter ist gebunden und gültig; input ist die aufgelöste Ausführung { word, args }.
• need_param — ein erforderlicher Parameter fehlt noch; der Body enthält param, description_i18n, free_text (ob zusätzlich eine Freitext-Eingabe angeboten werden soll) und die aufgezählten options.
• invalid — ein übergebener Wert ist ungültig; der Body enthält param, value und einen anzeigefertigen hint.

Treibe eine Auswahl an, indem du nach jedem erfassten Wert erneut resolve aufrufst, bis ready zurückkommt.

POST /api/commands/{word}/invoke

Derselbe Body wie bei resolve. Ist die Ausführung unvollständig oder ungültig, gibt invoke dieselbe need_param-/invalid-Anleitung zurück (niemals ein halb ausgeführter Befehl). Ist sie vollständig aufgelöst, kommt status: "executed" mit der aufgelösten invocation und einem gerenderten plan:

{
  "status": "executed",
  "invocation": { "word": "status", "args": {} },
  "plan": {
    "text": "Resolved /status",
    "html": false,
    "media": [],
    "affordances": [
      { "label": "/status", "action": { "word": "status", "args": {} } }
    ]
  }
}

Der plan ist eine oberflächenneutrale Antwort: text/html-Körper, optionale media (Bild, Screenshot, Datei oder Audio — per url oder Inline-data) und affordances (nächste Aktionen, jede mit einer wiederholbaren CommandInvocation, die ein Client als nativen Button / Komponente / nummerierte Taste rendert).

Achtung

Dieses Release liefert den Vertrag und die Resolve-/Invoke-Zustandsmaschine. Das oberflächenübergreifende Dispatching, das eine vollständige Domänenantwort rendert (Statustext, Task-Detail, …), liefert der Treiber jeder Oberfläche; das Web-Terminal behält vorerst seine eigene clientseitige Ableitung. Das Ausführen eines aufgelösten Befehls gibt eine strukturierte Bestätigung mit einer Replay-Affordanz zurück, was additiv ist — eine reichere Antwort zu verdrahten, bricht den Vertrag nicht.

Die vollständigen Request-/Response-Schemata stehen in der generierten Web-API-Referenz (Tag commands).