ComfyUI-OpenClaw/docs/release/operator_ux_contracts.md

Operator UX Acceleration Bundle Contracts

Version: 1.0.0 (Baseline) Date: 260216 Status: DRAFT -> FROZEN

This document defines the interface contracts for the Operator UX Acceleration Bundle (F49, F51, F52, F50).

1. Banner Status (F49)

Used by QueueMonitor and other UI components to display transient status or recovery guidance.

Schema (TypeScript)

type BannerSeverity = 'info' | 'success' | 'warning' | 'error';

interface BannerStatus {
  /** Unique identifier for deduplication (e.g., 'backpressure_123') */
  id: string;

  /** Visual severity level */
  severity: BannerSeverity;

  /** Display message */
  message: string;

  /** Source of the banner (e.g., 'system', 'queue', 'connectivity') */
  source: string;

  /** Time-to-live in milliseconds. If missing, persists until dismissed or replaced. */
  ttl_ms?: number;

  /** Whether the user can manually dismiss the banner */
  dismissible?: boolean;

  /** Optional clickable action */
  action?: {
    label: string;
    /** Target type: 'url' | 'tab' | 'action' */
    type: string;
    /** Target value (URL, tab ID, or action name) */
    payload: string;
  };
}

F49 Baseline (Current Behavior)

• Monitoring: Polls /health every 10s.
• Triggers: Checks stats.observability.total_dropped > 0.
• Display: Simple DOM injection of canonical .openclaw-banner markup; legacy .moltbot-banner compatibility selectors remain available through centralized runtime aliasing.
• Connectivity posture: Queue-monitor disconnect warnings should tolerate initial sidebar/bootstrap races and only escalate after bounded repeated failure or post-healthy disconnect evidence, so transient startup misses do not become durable incident noise.
• Limitations: No 'info'/'success' states, simplistic dedupe.

1.1 Notification Center (F66)

Persistent operator notifications are the durable counterpart to transient banners and toasts.

Schema (TypeScript)

interface NotificationEntry {
  id: string;
  severity: BannerSeverity;
  message: string;
  source: string;
  created_at: string;
  updated_at: string;
  count: number;
  acknowledged_at?: string | null;
  dismissed_at?: string | null;
  action?: {
    label: string;
    type: 'url' | 'tab' | 'action';
    payload: string;
  };
  metadata?: Record<string, unknown>;
}

F66 Baseline

• Warning/error banners and selected operator toasts are mirrored into the in-app notification center.
• Entries are deduplicated by source-specific keys and persisted in local storage across reloads.
• Dismiss hides an entry from the active list without deleting the historical record from storage.
• Acknowledge clears unread state while keeping the entry visible.
• Notification message / source fields are treated as untrusted text at the render sink and must stay escaped before DOM insertion; notification content is not a supported HTML surface.
• Sources with jump targets should attach a tab/action deep link so operators can navigate directly to the affected surface.
• Canonical openclaw-* DOM/class ownership should be authored once in the shell/templates; any retained moltbot-* class compatibility must come from shared runtime alias helpers instead of duplicated markup.

2. Context Actions (F51)

Defines quick actions available in the node context menu (via ComfyUI extension hooks).

Schema (TypeScript)

interface ContextAction {
  /** Unique action ID */
  id: string;

  /** Display label */
  label: string;

  /** Optional icon class or emoji */
  icon?: string;

  /** Primary target category */
  target: 'explorer' | 'jobs' | 'settings' | 'doctor' | 'url';

  /** Context data required for the action */
  payload?: {
    node_type?: string;
    node_id?: string;
    widget_name?: string;
    [key: string]: any;
  };

  /** Filter function to determine availability (frontend-side) */
  condition?: (node: any) => boolean;
}

3. Parameter Lab

Contracts for bounded parameter sweeps and experiment orchestration.

Sweep Request Schema (JSON)

{
  "workflow_json": "...",
  "params": [
    {
      "node_id": "10",
      "widget_name": "cfg",
      "values": [6.0, 7.0, 8.0],
      "strategy": "grid"
    },
    {
      "node_id": "loader-alpha",
      "widget_name": "seed",
      "values": [41, 42]
    }
  ]
}

Contract notes:

• node_id is a string-preserving host graph identifier. It may be numeric text such as "10" or a non-numeric host ID, and clients must not coerce it to a number when storing, comparing, or replaying experiment parameters.
• Experiment parameter keys such as "10.cfg" are display/storage keys derived from the original node_id plus widget_name; they are not a separate numeric node contract.
• Sweep values are limited to bounded strings, booleans, integers, and finite numbers. Null, arrays, objects, non-finite numbers, overlong strings, presentation-ambiguous duplicates, and unsupported strategies fail validation instead of being coerced.
• Sweep creation supports grid strategy only. The backend policy is authoritative and limits a request to 5 MiB, workflow text to 4 MiB, eight dimensions, 50 values per dimension, and 50 generated combinations. Compare creation accepts at most eight scalar items.

Queue ownership receipt

• The coordinator observes the host's reviewed promptQueueing and promptQueued request boundaries, correlating their integer requestId and batchCount fields.
• It writes a transient UUID receipt only into the matching serialized workflow and returns the exact promptId / requestId pair used to route bounded lifecycle event metadata.
• Unsupported event APIs, malformed or missing boundaries, pre-existing unobserved host queue activity, receipt collisions, timeouts, and ambiguous batch ownership fail explicitly. There is no fallback to a globally recent prompt ID.

Experiment Result Schema (JSON)

{
  "experiment_id": "exp_abc123",
  "run_id": "run_xyz789",
  "timestamp": 1234567890,
  "params": {
    "10.cfg": 7.0,
    "3.seed": 42
  },
  "status": "completed",
  "outputs": {
    "9.image": ["filename_1.png"]
  },
  "error": null
}

4. Model Compare (F50)

Contracts for multi-model side-by-side comparison.

Compare Request Schema (JSON)

{
  "prompt": "User input text...",
  "candidates": [
    { "provider": "openai", "model": "gpt-4o" },
    { "provider": "anthropic", "model": "claude-3-5-sonnet" }
  ],
  "config": {
    "temperature": 0.7,
    "max_tokens": 1000
  },
  "timeout_ms": 30000
}

Compare Result Schema (JSON)

{
  "run_id": "cmp_def456",
  "candidates": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "output": "Result A...",
      "latency_ms": 1200,
      "cost_usd": 0.001,
      "error": null
    },
    {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet",
      "output": "Result B...",
      "latency_ms": 1400,
      "cost_usd": 0.003,
      "error": null
    }
  ]
}