UIAP Action Runtime

UIAP Action Runtime Spec v0.1

Feld	Wert
Status	Draft
Version	0.1
Datum	2026-03-27
Abhängigkeiten	[UIAP-CORE], [UIAP-CAP]
Editoren	Patrick

1. Zweck

UIAP Action Runtime v0.1 definiert, wie eine UIAP-Gegenstelle eine angeforderte Action annimmt, das Ziel auflöst, Actionability prüft, die Ausführung wählt, den Erfolg verifiziert und strukturierte Ergebnisse zurückmeldet.

Die Runtime ist nicht auf Web beschränkt, enthält hier aber eine normative Web-Bindung über [email protected].

Normative Begriffe

Die Schlüsselwörter MUSS, DARF NICHT, SOLLTE, KANN in diesem Dokument sind normativ gemäss RFC 2119 und BCP 14 zu interpretieren, wenn und nur wenn sie in GROSSBUCHSTABEN erscheinen.

2. Konformitätsklassen

2.1 Runtime Executor

Der Executor nimmt action.request entgegen und führt aus.

2.2 Runtime Controller

Der Controller sendet action.request, action.cancel und Confirmation-Antworten.

2.3 Runtime Presenter

Optional. Zeigt Ghost Cursor, Highlights, Fokusrahmen oder Narration an.

---

3. Grundprinzipien

1. Eine Action MUSS einen klaren Lifecycle haben.
2. Nicht-idempotente Actions DÜRFEN nicht blind wiederholt werden.
3. Zielauflösung MUSS deterministisch und prüfbar sein.
4. Erfolg MUSS über beobachtbare Signale verifiziert werden.
5. User-Activation- und Trusted-Event-Grenzen MÜSSEN explizit modelliert werden.
6. Presentation ist optional und darf die Ausführung nicht fälschen.

---

4. Runtime-Zustände

Eine Action hat genau einen dieser Zustände:

• RECEIVED
• RESOLVING_TARGET
• CHECKING_PRECONDITIONS
• AWAITING_CONFIRMATION
• EXECUTING
• VERIFYING
• WAITING_FOR_USER
• RECOVERING
• SUCCEEDED
• FAILED
• CANCELLED

---

5. Nachrichtentypen der Runtime

5.1 action.request

Request

interface ActionRequestPayload {
  actionId: ActionId;

  target?: ActionTarget;
  args?: Record<string, unknown>;

  preferredExecutionModes?: ExecutionMode[];
  verification?: VerificationSpec;
  presentation?: PresentationHints;

  timeoutMs?: number;
  idempotencyKey?: string;

  metadata?: Record<string, unknown>;
}

interface ActionTarget {
  ref?: TargetRef;

  expectedRole?: UIRole;
  expectedName?: string;
  expectedScopeId?: ScopeId;
  expectedDocumentId?: DocumentId;

  allowAmbiguous?: false;       // default false
}

interface PresentationHints {
  ghostCursor?: boolean;
  highlight?: "none" | "outline" | "spotlight";
  narration?: string;
  pace?: "instant" | "humanized";
}

Response: action.accepted

interface ActionAcceptedPayload {
  actionHandle: string;
  actionId: ActionId;
  status: "accepted";
}

Regeln

• Eine gültige action.request MUSS mit action.accepted oder error beantwortet werden.
• actionHandle MUSS innerhalb der Session eindeutig sein.

---

5.2 action.progress

interface ActionProgressPayload {
  actionHandle: string;
  stage:
    | "resolving_target"
    | "checking_preconditions"
    | "awaiting_confirmation"
    | "executing"
    | "verifying"
    | "waiting_for_user"
    | "recovering";

  chosenExecutionMode?: ExecutionMode;
  resolvedTarget?: ResolvedTarget;
  note?: string;
  detail?: Record<string, unknown>;
}

---

5.3 action.confirmation.request

interface ActionConfirmationRequestPayload {
  actionHandle: string;
  actionId: ActionId;

  risk: RiskDescriptor;
  preview?: {
    summary?: string;
    target?: ResolvedTarget;
    args?: Record<string, unknown>;
  };
}

5.4 action.confirmation.grant

interface ActionConfirmationGrantPayload {
  actionHandle: string;
}

5.5 action.confirmation.deny

interface ActionConfirmationDenyPayload {
  actionHandle: string;
  reason?: string;
}

Regeln

• Wenn risk.level="confirm" oder Policy dies verlangt, MUSS der Executor action.confirmation.request senden und anhalten.
• Ohne action.confirmation.grant DARF die Action nicht fortgesetzt werden.
• Eine Verweigerung MUSS mit action.result.status="cancelled" enden.

---

5.6 action.cancel

interface ActionCancelPayload {
  actionHandle: string;
  reason?: string;
}

5.7 action.cancelled

interface ActionCancelledPayload {
  actionHandle: string;
  status: "cancelled";
  reason?: string;
}

---

5.8 action.result

interface ActionResultPayload {
  actionHandle: string;
  actionId: ActionId;

  status: "succeeded" | "failed" | "cancelled";

  chosenExecutionMode?: ExecutionMode;
  resolvedTarget?: ResolvedTarget;

  verification: VerificationOutcome;
  sideEffectState?: "none" | "applied" | "unknown";

  stateRevision?: RevisionId;
  returnValue?: Record<string, unknown>;
  error?: RuntimeErrorDescriptor;

  metadata?: Record<string, unknown>;
}

---

6. Hilfstypen der Runtime

6.1 ResolvedTarget

interface ResolvedTarget {
  by: "stableId" | "instanceId" | "semantic" | "annotation" | "runtimeHint";
  instanceId: ElementInstanceId;
  stableId?: StableId;
  documentId: DocumentId;
  scopeId?: ScopeId;
  role: UIRole;
  name?: string;
  bbox?: DOMRectLike;
}

---

6.2 VerificationSpec

interface VerificationSpec {
  policy?: "capability-default" | "any" | "all" | "none";
  signals?: SuccessSignal[];
  timeoutMs?: number;
  requireRevisionAdvance?: boolean;
}

---

6.3 VerificationOutcome

interface VerificationOutcome {
  passed: boolean;
  policy: "capability-default" | "any" | "all" | "none";
  observed: SuccessSignal[];
  missing?: SuccessSignal[];
  timeoutMs?: number;
}

---

6.4 RuntimeErrorDescriptor

type RuntimeErrorCode =
  | "action_unsupported"
  | "target_required"
  | "target_not_found"
  | "target_ambiguous"
  | "stale_target"
  | "target_not_interactable"
  | "confirmation_denied"
  | "user_activation_required"
  | "cross_origin_unavailable"
  | "closed_shadow_unavailable"
  | "execution_mode_unavailable"
  | "verification_failed"
  | "unsafe_retry_refused"
  | "cancelled"
  | "internal_runtime_error";

interface RuntimeErrorDescriptor {
  code: RuntimeErrorCode;
  message: string;
  retryable?: boolean;
  detail?: Record<string, unknown>;
}

---

7. Empfohlene Ausführungsreihenfolge

Die Runtime SOLLTE standardmäßig diesen Modus-Fallback verwenden:

1. appAction
2. semanticUi
3. externalDriver
4. inputSynthesis
5. visionAssist

Begründung

• appAction ist fachlich am stabilsten.
• semanticUi nutzt die vorhandene Web-Semantik.
• externalDriver kann echte Browsersteuerung leisten.
• inputSynthesis im Seitenkontext ist oft nur begrenzt vertrauenswürdig.
• visionAssist ist teuer und fragiler.

Die konkrete Reihenfolge DARF pro App oder Policy angepasst werden.

---

8. Zielauflösung

8.1 Auflösungsreihenfolge

Ein Executor MUSS Targets in dieser Reihenfolge auflösen:

1. TargetRef.by = "stableId"
2. TargetRef.by = "semantic" innerhalb erwarteter Scopes/Dokumente
3. app-spezifische Annotationen wie meaning oder defaultAction
4. lokale Runtime-Hints (css, xpath) nur als letzter technischer Fallback

8.2 Disambiguierung

Wenn mehrere Kandidaten gefunden werden, MUSS der Executor einen Score bilden aus:

• Scope-Match
• Role-Match
• Name-Match
• StableId-Match
• sichtbarer Nähe zum aktuellen Fokus
• deklarierter Default-Action

Wenn danach kein eindeutiger Sieger vorliegt, MUSS target_ambiguous geliefert werden.

8.3 Stale Targets

Wenn ein bereits aufgelöstes Ziel vor der Ausführung nicht mehr attached oder nicht mehr konsistent ist, MUSS die Runtime einmal neu auflösen. Wenn auch das fehlschlägt, MUSS stale_target oder target_not_found geliefert werden.

---

9. Precondition- und Actionability-Prüfung

Playwright behandelt robuste Interaktion nicht als „einfach draufklicken“, sondern prüft vor Aktionen Zustände wie Sichtbarkeit, Stabilität, Event-Empfang und Enabled-Status. UIAP übernimmt dieses Denkmodell ausdrücklich, weil Browser-UIs sonst bei jedem Re-Render anfangen, sich wie beleidigte Primadonnen aufzuführen. scrollIntoView() ist das Standardmittel, um Ziele sichtbar zu machen. ([Playwright][4])

Vor einer Ausführung MUSS der Executor mindestens prüfen:

9.1 Allgemein

• Session ist aktiv
• Action wird unterstützt
• Policy erlaubt die Action
• Ziel ist vorhanden
• Ziel gehört nicht zu einem opaque Bereich

9.2 Für pointer-ähnliche Actions (ui.activate, ui.toggle, ui.choose)

• attached = true
• visible = true
• enabled != false
• blocked != true
• stable != false
• obscured != true oder es gibt eine sichere Recovery
• Ziel ist im Viewport oder kann dorthin gescrollt werden

9.3 Für Texteingabe (ui.enterText, ui.clearText, ui.setValue)

• editable = true oder Rolle ist textuell editierbar
• readonly != true
• enabled != false
• Ziel kann fokussiert werden oder ist bereits fokussiert

9.4 Für nav.navigate

• Zielroute oder Link muss vorhanden oder direkt ausführbar sein

Wenn eine Prüfung scheitert, MUSS entweder Recovery versucht oder ein Fehler resultiert werden.

---

10. Ausführungsmodi

10.1 appAction

Direkte fachliche Ausführung über eine App-Registry.

Regeln

• SOLLTE bevorzugt werden, wenn verfügbar.
• MUSS die fachliche Bedeutung der Action respektieren.
• DARF ohne konkretes DOM-Ziel ausgeführt werden, wenn die Action dies zulässt.

---

10.2 semanticUi

Semantische Ausführung im Web-Kontext.

Regeln

• SOLLTE Plattformmethoden wie focus(), click(), scrollIntoView() oder kontrollspezifische Setter bevorzugen.
• SOLLTE nur synthetische Eventsequenzen erzeugen, wenn keine semantisch reichere Methode existiert.
• DARF sich nicht auf rohe dispatchEvent()-Tricks als Standard verlassen.

HTMLElement.click() simuliert einen Klick und feuert das Click-Event, sofern das Element nicht disabled ist. Per dispatchEvent() erzeugte Events sind dagegen nicht isTrusted, und Features mit Aktivierungszwang verlangen laut Plattform trusted triggering input events. Deshalb MUSS die Runtime user_activation_required als erstklassigen Fall behandeln, statt so zu tun, als würde JavaScript allein eine echte Nutzerinteraktion herbeizaubern. ([MDN Web Docs][5])

---

10.3 externalDriver

Ausführung über externe Browsersteuerung.

Regeln

• DARF verwendet werden, wenn ein Out-of-Process-Driver verfügbar ist.
• MUSS denselben Action-Lifecycle und dieselben Verification-Regeln einhalten.
• WebDriver BiDi oder äquivalente Mechanismen SIND zulässige Implementierungen.

---

10.4 inputSynthesis

Low-Level-Eingabesynthese.

Regeln

• DARF verwendet werden, wenn semanticUi nicht ausreicht.
• Ein In-Page-Executor MUSS diesen Modus als nicht user-activation-sicher behandeln.
• Dieser Modus SOLLTE nicht für sicherheitskritische oder browsergated Flows verwendet werden.

---

10.5 visionAssist

Visueller Fallback.

Regeln

• DARF nur verwendet werden, wenn die anderen Modi nicht verfügbar oder erfolglos sind.
• MUSS den gewählten Zielpunkt und die nachgelagerte Verifikation dokumentieren.

---

11. Semantik der Primitive Actions

11.1 ui.read

Liest Zustand, Text, Value oder Beschreibung eines Targets.

Ergebnis

• returnValue SOLLTE den gelesenen Zustand oder Inhalt tragen.

11.2 ui.focus

Fokussiert das Ziel.

Erfolg

• focus.target == instanceId

11.3 ui.highlight

Reine Präsentationsaction.

Erfolg

• Muss nicht den Web-State ändern.
• verification.policy="none" ist zulässig.

11.4 ui.activate

Aktiviert ein Ziel.

Web-Bindung

• Bevorzugt appAction
• sonst semanticUi mit scrollIntoView() und Aktivierung
• nur wenn nötig andere Modi

Erfolg

• capability-default oder angeforderte Success Signals

11.5 ui.enterText

Schreibt Text in ein editierbares Feld.

Web-Bindung

• Ziel fokussieren
• optional bestehenden Wert löschen
• Wert setzen
• app-kompatible Eingabesemantik auslösen
• Ergebniswert verifizieren

Erfolg

• value.equals oder element.state.textValue

11.6 ui.clearText

Setzt textuellen Inhalt auf leer.

11.7 ui.choose

Wählt eine Option in combobox, listbox, select oder ähnlichen Kontrollen.

11.8 ui.toggle

Ändert einen binären oder tri-state Zustand.

11.9 ui.expand / ui.collapse

Öffnet bzw. schließt expandierbare Ziele.

11.10 ui.open / ui.close

Öffnet oder schließt modale oder temporäre Oberflächen.

11.11 ui.scrollIntoView

Bringt ein Ziel in den sichtbaren Bereich.

11.12 ui.scroll

Scrollt ein Element oder den Viewport.

11.13 ui.submit

Schließt eine formularähnliche Interaktion ab.

11.14 nav.navigate

Wechselt Route oder URL.

11.15 app.invoke

Führt eine deklarierte Domain Action aus.

---

12. Verification

12.1 Default-Verhalten

Wenn verification nicht gesetzt ist, MUSS die Runtime folgendes verwenden:

1. success-Signale aus dem ActionDescriptor, falls vorhanden
2. sonst success-Signale des Ziels, falls vorhanden
3. sonst eine profiltypische Minimalverifikation

12.2 Minimalverifikation im Web

Für Web SOLLTE Minimalverifikation so aussehen:

• bei ui.focus: Fokus ist auf dem Ziel
• bei ui.enterText: Zielwert entspricht erwartetem Wert
• bei ui.activate: mindestens eine plausible Zustandsänderung, z. B. Route-Wechsel, Dialogwechsel, Toast, Zustandsdelta
• bei nav.navigate: Route oder URL hat gewechselt
• bei ui.highlight: keine State-Verifikation nötig

12.3 Verification Policies

• none: keine formale Verifikation
• any: mindestens ein Signal muss eintreten
• all: alle Signale müssen eintreten
• capability-default: app- oder zielseitige Defaults

12.4 Revision Advance

Wenn requireRevisionAdvance=true, MUSS mindestens eine neue PageGraph-Revision beobachtet werden, bevor Erfolg erklärt wird.

---

13. Recovery

Die Runtime DARF Recovery-Versuche machen, MUSS aber vorsichtig bleiben.

13.1 Zulässige automatische Recovery

• erneut auflösen bei stale target
• scrollIntoView bei offscreen target
• kurze Re-Waits bei vorübergehendem Busy-/Loading-Zustand
• erneute Verifikation nach dokumentierter UI-Aktualisierung

13.2 Nicht zulässige automatische Recovery

• erneutes Auslösen nicht-idempotenter Actions ohne sichere Kenntnis des Side-Effect-Status
• Überspringen nötiger Bestätigungen
• Zugriff in opaque Cross-Origin- oder Closed-Shadow-Bereiche

13.3 Side-Effect-Status

Bei Fehlschlag MUSS sideEffectState gesetzt werden auf:

• none
• applied
• unknown

Für nicht-idempotente Actions MUSS unknown als hartes Warnsignal behandelt werden.

---

14. User-Handoff und Aktivierung

Das Web begrenzt bewusst APIs, die schlechte Nutzererfahrungen oder Missbrauch verursachen könnten; einige Features funktionieren nur bei aktiver oder bereits erfolgter User Activation, und die auslösenden Input-Events müssen trusted sein. Deshalb MUSS UIAP eine Action sauber anhalten und waiting_for_user oder user_activation_required melden können, statt Browser-Sicherheitsgrenzen mit Script-Zauberei wegzudiskutieren. ([MDN Web Docs][2])

Wenn eine Action daran scheitert, MUSS der Executor:

1. action.progress mit stage="waiting_for_user" senden,
2. einen verständlichen note-Text publizieren,
3. nach tatsächlicher Nutzerinteraktion FORTSETZEN oder sauber FEHLSCHLAGEN.

---

15. Runtime-Fehlerregeln

15.1 target_not_found

Kein passendes Ziel gefunden.

15.2 target_ambiguous

Mehrere plausible Ziele, kein eindeutiger Sieger.

15.3 target_not_interactable

Ziel existiert, ist aber nicht ausführbar.

15.4 user_activation_required

Ausführung benötigt echte Nutzerinteraktion.

15.5 cross_origin_unavailable

Ziel liegt in einem opaque Cross-Origin-Bereich.

15.6 closed_shadow_unavailable

Ziel liegt in einem geschlossenen Shadow Root ohne Bridge.

15.7 verification_failed

Ausführung lief, aber erwartete Signale blieben aus.

15.8 unsafe_retry_refused

Retry wäre fachlich oder sicherheitstechnisch unzulässig.

---

16. Minimaler Runtime-Konformitätsumfang

Ein konformer Runtime Executor MUSS:

• action.request annehmen,
• Zielauflösung aus stableId und semantischen Targets unterstützen,
• Precondition Checks ausführen,
• mindestens appAction oder semanticUi unterstützen,
• Confirmation Flows unterstützen,
• Success Signals verifizieren,
• action.result mit verification und optional error senden.

---

17. Beispiel: ui.activate auf einen Submit-Button

Request

{
  "uiap": "0.1",
  "kind": "request",
  "type": "action.request",
  "id": "msg_77",
  "sessionId": "sess_123",
  "ts": "2026-03-26T14:03:00.000Z",
  "source": { "role": "agent", "id": "onboarding-agent" },
  "payload": {
    "actionId": "ui.activate",
    "target": {
      "ref": { "by": "stableId", "value": "video.submit" },
      "expectedRole": "button",
      "expectedName": "Video erstellen"
    },
    "verification": {
      "policy": "all",
      "signals": [
        { "kind": "route.changed", "pattern": "/videos/:id" },
        { "kind": "toast.contains", "text": "erstellt" }
      ],
      "timeoutMs": 8000,
      "requireRevisionAdvance": true
    },
    "presentation": {
      "ghostCursor": true,
      "highlight": "spotlight",
      "pace": "humanized"
    },
    "timeoutMs": 12000
  }
}

Sofortantwort

{
  "uiap": "0.1",
  "kind": "response",
  "type": "action.accepted",
  "id": "msg_78",
  "correlationId": "msg_77",
  "sessionId": "sess_123",
  "ts": "2026-03-26T14:03:00.015Z",
  "source": { "role": "bridge", "id": "web-runtime" },
  "payload": {
    "actionHandle": "act_991",
    "actionId": "ui.activate",
    "status": "accepted"
  }
}

Progress

{
  "uiap": "0.1",
  "kind": "event",
  "type": "action.progress",
  "id": "msg_79",
  "sessionId": "sess_123",
  "ts": "2026-03-26T14:03:00.020Z",
  "source": { "role": "bridge", "id": "web-runtime" },
  "payload": {
    "actionHandle": "act_991",
    "stage": "resolving_target",
    "resolvedTarget": {
      "by": "stableId",
      "instanceId": "el_submit",
      "stableId": "video.submit",
      "documentId": "doc_root",
      "scopeId": "scope_form",
      "role": "button",
      "name": "Video erstellen",
      "bbox": { "x": 120, "y": 420, "width": 180, "height": 40 }
    }
  }
}

Result

{
  "uiap": "0.1",
  "kind": "event",
  "type": "action.result",
  "id": "msg_80",
  "sessionId": "sess_123",
  "ts": "2026-03-26T14:03:01.220Z",
  "source": { "role": "bridge", "id": "web-runtime" },
  "payload": {
    "actionHandle": "act_991",
    "actionId": "ui.activate",
    "status": "succeeded",
    "chosenExecutionMode": "semanticUi",
    "resolvedTarget": {
      "by": "stableId",
      "instanceId": "el_submit",
      "stableId": "video.submit",
      "documentId": "doc_root",
      "scopeId": "scope_form",
      "role": "button",
      "name": "Video erstellen"
    },
    "verification": {
      "passed": true,
      "policy": "all",
      "observed": [
        { "kind": "route.changed", "pattern": "/videos/:id" },
        { "kind": "toast.contains", "text": "erstellt" }
      ],
      "timeoutMs": 8000
    },
    "sideEffectState": "applied",
    "stateRevision": "rev_20"
  }
}

---

Normative Referenzen

• [UIAP-CORE] UIAP Core v0.1
• [UIAP-CAP] UIAP Capability Model v0.1
• [RFC2119] Key words for use in RFCs to Indicate Requirement Levels, BCP 14

Security Considerations

• Action-Handler MÜSSEN Eingabeparameter validieren, bevor sie fachliche Operationen ausführen.
• sideEffectState MUSS korrekt gemeldet werden, um unbeabsichtigte Zustandsänderungen nachvollziehbar zu machen.
• Nicht-idempotente Actions SOLLTEN keine automatischen Retries ausführen.
• Der Confirmation-Flow MUSS manipulationssicher sein; eine granted-Antwort DARF nur von einer autorisierten Quelle stammen.

Changelog

Version	Datum	Änderungen
0.1	2026-03-27	Initialer Entwurf