Merge branch 'master' into feature/generic-feature-flag-cli

Adds two optional, nullable UUID fields to PromptRequest for runtimes
that wrap workflow execution in a workflow-version entity (the
hosted-cloud runtime does this; local ComfyUI does not). Both fields
are tagged `x-runtime: [cloud]` to mark them as runtime-specific —
local ComfyUI returns `null` (or omits them entirely) and that's
correct behavior, not drift.

## Why these fields belong in the OSS spec

Hosted-cloud's frontend and backend share `openapi.yaml` as their
single source of truth via auto-generated client types. Without the
fields declared in the spec, the cloud runtime has to either:

  1. Hand-edit a vendored copy of openapi.yaml (drift between vendor
     and upstream — unsustainable).
  2. Maintain a separate cloud-only spec file (forks the contract,
     defeats the point of a shared OSS spec).

Both options have been tried and both produce maintenance pain. The
shape that scales is: cloud-only fields live in OSS spec under their
intended path, declared nullable, with an explicit `x-runtime` tag so
local-only readers can ignore them programmatically and human readers
can see what each runtime populates.

## About the `x-runtime` extension

This is the first use of `x-runtime` in this spec. Convention:

  - `x-runtime: [cloud]` — only the hosted-cloud runtime populates the
    field; local returns null or omits.
  - `x-runtime: [local]` — only local populates; cloud returns null.
  - Tag absent — both runtimes populate the field (the default).

This is a vendor extension (`x-` prefix) and is ignored by spec
validators that don't recognize it, including `kin-openapi`. Local
clients reading the spec see two extra optional nullable fields, which
is forward-compatible with all existing readers.

## What this does not change

  - No Python code changes. `PromptRequest` already accepts arbitrary
    optional fields (`extra_data: additionalProperties: true` on the
    same schema is a stronger guarantee). The Python server already
    silently accepts and ignores both fields today.
  - No required-fields change. Both fields stay outside `required`,
    so older clients that don't know about them keep validating.
  - No nullability widening on existing fields.

## Verification

  - YAML parses (`yaml.safe_load`).
  - `kin-openapi` `loader.LoadFromFile` accepts the modified spec.
  - `openapi3filter.ValidateRequest` on a PromptRequest with both
    fields set to `null`, set to a valid UUID, or omitted — all pass.

comfy/cli_args.py

@@ -238,6 +238,8 @@ database_default_path = os.path.abspath(
 )
 parser.add_argument("--database-url", type=str, default=f"sqlite:///{database_default_path}", help="Specify the database URL, e.g. for an in-memory database you can use 'sqlite:///:memory:'.")
 parser.add_argument("--enable-assets", action="store_true", help="Enable the assets system (API routes, database synchronization, and background scanning).")
+parser.add_argument("--feature-flag", type=str, action='append', default=[], metavar="KEY[=VALUE]", help="Set a server feature flag. Use KEY=VALUE to set an explicit value, or bare KEY to set it to true. Can be specified multiple times. Boolean values (true/false) and numbers are auto-converted. Examples: --feature-flag show_signin_button=true  or  --feature-flag show_signin_button")
+parser.add_argument("--list-feature-flags", action="store_true", help="Print the registry of known CLI-settable feature flags as JSON and exit.")
 
 if comfy.options.args_parsing:
     args = parser.parse_args()

comfy/k_diffusion/sampling.py

@@ -1810,119 +1810,3 @@ def sample_sa_solver(model, x, sigmas, extra_args=None, callback=None, disable=F
 def sample_sa_solver_pece(model, x, sigmas, extra_args=None, callback=None, disable=False, tau_func=None, s_noise=1.0, noise_sampler=None, predictor_order=3, corrector_order=4, simple_order_2=False):
     """Stochastic Adams Solver with PECE (Predict–Evaluate–Correct–Evaluate) mode (NeurIPS 2023)."""
     return sample_sa_solver(model, x, sigmas, extra_args=extra_args, callback=callback, disable=disable, tau_func=tau_func, s_noise=s_noise, noise_sampler=noise_sampler, predictor_order=predictor_order, corrector_order=corrector_order, use_pece=True, simple_order_2=simple_order_2)
-
-
-@torch.no_grad()
-def sample_ar_video(model, x, sigmas, extra_args=None, callback=None, disable=None,
-                    num_frame_per_block=1):
-    """
-    Autoregressive video sampler: block-by-block denoising with KV cache
-    and flow-match re-noising for Causal Forcing / Self-Forcing models.
-
-    Requires a Causal-WAN compatible model (diffusion_model must expose
-    init_kv_caches / init_crossattn_caches) and 5-D latents [B,C,T,H,W].
-
-    All AR-loop parameters are passed via the SamplerARVideo node, not read
-    from the checkpoint or transformer_options.
-    """
-    extra_args = {} if extra_args is None else extra_args
-    model_options = extra_args.get("model_options", {})
-    transformer_options = model_options.get("transformer_options", {})
-
-    if x.ndim != 5:
-        raise ValueError(
-            f"ar_video sampler requires 5-D video latents [B,C,T,H,W], got {x.ndim}-D tensor with shape {x.shape}. "
-            "This sampler is only compatible with autoregressive video models (e.g. Causal-WAN)."
-        )
-
-    inner_model = model.inner_model.inner_model
-    causal_model = inner_model.diffusion_model
-
-    if not (hasattr(causal_model, "init_kv_caches") and hasattr(causal_model, "init_crossattn_caches")):
-        raise TypeError(
-            "ar_video sampler requires a Causal-WAN compatible model whose diffusion_model "
-            "exposes init_kv_caches() and init_crossattn_caches(). The loaded checkpoint "
-            "does not support this interface — choose a different sampler."
-        )
-
-    seed = extra_args.get("seed", 0)
-
-    bs, c, lat_t, lat_h, lat_w = x.shape
-    frame_seq_len = -(-lat_h // 2) * -(-lat_w // 2) # ceiling division
-    num_blocks = -(-lat_t // num_frame_per_block)   # ceiling division
-    device = x.device
-    model_dtype = inner_model.get_dtype()
-
-    kv_caches = causal_model.init_kv_caches(bs, lat_t * frame_seq_len, device, model_dtype)
-    crossattn_caches = causal_model.init_crossattn_caches(bs, device, model_dtype)
-
-    output = torch.zeros_like(x)
-    s_in = x.new_ones([x.shape[0]])
-    current_start_frame = 0
-
-    # I2V: seed KV cache with the initial image latent before the denoising loop
-    initial_latent = ar_config.get("initial_latent", None)
-    if initial_latent is not None:
-        initial_latent = inner_model.process_latent_in(initial_latent).to(device=device, dtype=model_dtype)
-        n_init = initial_latent.shape[2]
-        output[:, :, :n_init] = initial_latent
-
-        ar_state = {"start_frame": 0, "kv_caches": kv_caches, "crossattn_caches": crossattn_caches}
-        transformer_options["ar_state"] = ar_state
-        zero_sigma = sigmas.new_zeros([1])
-        _ = model(initial_latent, zero_sigma * s_in, **extra_args)
-
-        current_start_frame = n_init
-        remaining = lat_t - n_init
-        num_blocks = -(-remaining // num_frame_per_block)
-
-    num_sigma_steps = len(sigmas) - 1
-    total_real_steps = num_blocks * num_sigma_steps
-    step_count = 0
-
-    try:
-        for block_idx in trange(num_blocks, disable=disable):
-            bf = min(num_frame_per_block, lat_t - current_start_frame)
-            fs, fe = current_start_frame, current_start_frame + bf
-            noisy_input = x[:, :, fs:fe]
-
-            ar_state = {
-                "start_frame": current_start_frame,
-                "kv_caches": kv_caches,
-                "crossattn_caches": crossattn_caches,
-            }
-            transformer_options["ar_state"] = ar_state
-
-            for i in range(num_sigma_steps):
-                denoised = model(noisy_input, sigmas[i] * s_in, **extra_args)
-
-                if callback is not None:
-                    scaled_i = step_count * num_sigma_steps // total_real_steps
-                    callback({"x": noisy_input, "i": scaled_i, "sigma": sigmas[i],
-                              "sigma_hat": sigmas[i], "denoised": denoised})
-
-                if sigmas[i + 1] == 0:
-                    noisy_input = denoised
-                else:
-                    sigma_next = sigmas[i + 1]
-                    torch.manual_seed(seed + block_idx * 1000 + i)
-                    fresh_noise = torch.randn_like(denoised)
-                    noisy_input = (1.0 - sigma_next) * denoised + sigma_next * fresh_noise
-
-                    for cache in kv_caches:
-                        cache["end"] -= bf * frame_seq_len
-
-                step_count += 1
-
-            output[:, :, fs:fe] = noisy_input
-
-            for cache in kv_caches:
-                cache["end"] -= bf * frame_seq_len
-            zero_sigma = sigmas.new_zeros([1])
-            _ = model(noisy_input, zero_sigma * s_in, **extra_args)
-
-            current_start_frame += bf
-    finally:
-        transformer_options.pop("ar_state", None)
-
-    return output

comfy/ldm/wan/ar_model.py

@@ -1,276 +0,0 @@
-"""
-CausalWanModel: Wan 2.1 backbone with KV-cached causal self-attention for
-autoregressive (frame-by-frame) video generation via Causal Forcing.
-
-Weight-compatible with the standard WanModel -- same layer names, same shapes.
-The difference is purely in the forward pass: this model processes one temporal
-block at a time and maintains a KV cache across blocks.
-
-Reference: https://github.com/thu-ml/Causal-Forcing
-"""
-
-import torch
-import torch.nn as nn
-
-from comfy.ldm.modules.attention import optimized_attention
-from comfy.ldm.flux.math import apply_rope1
-from comfy.ldm.wan.model import (
-    sinusoidal_embedding_1d,
-    repeat_e,
-    WanModel,
-    WanAttentionBlock,
-)
-import comfy.ldm.common_dit
-import comfy.model_management
-
-
-class CausalWanSelfAttention(nn.Module):
-    """Self-attention with KV cache support for autoregressive inference."""
-
-    def __init__(self, dim, num_heads, window_size=(-1, -1), qk_norm=True,
-                 eps=1e-6, operation_settings={}):
-        assert dim % num_heads == 0
-        super().__init__()
-        self.dim = dim
-        self.num_heads = num_heads
-        self.head_dim = dim // num_heads
-        self.qk_norm = qk_norm
-        self.eps = eps
-
-        ops = operation_settings.get("operations")
-        device = operation_settings.get("device")
-        dtype = operation_settings.get("dtype")
-
-        self.q = ops.Linear(dim, dim, device=device, dtype=dtype)
-        self.k = ops.Linear(dim, dim, device=device, dtype=dtype)
-        self.v = ops.Linear(dim, dim, device=device, dtype=dtype)
-        self.o = ops.Linear(dim, dim, device=device, dtype=dtype)
-        self.norm_q = ops.RMSNorm(dim, eps=eps, elementwise_affine=True, device=device, dtype=dtype) if qk_norm else nn.Identity()
-        self.norm_k = ops.RMSNorm(dim, eps=eps, elementwise_affine=True, device=device, dtype=dtype) if qk_norm else nn.Identity()
-
-    def forward(self, x, freqs, kv_cache=None, transformer_options={}):
-        b, s, n, d = *x.shape[:2], self.num_heads, self.head_dim
-
-        q = apply_rope1(self.norm_q(self.q(x)).view(b, s, n, d), freqs)
-        k = apply_rope1(self.norm_k(self.k(x)).view(b, s, n, d), freqs)
-        v = self.v(x).view(b, s, n, d)
-
-        if kv_cache is None:
-            x = optimized_attention(
-                q.view(b, s, n * d),
-                k.view(b, s, n * d),
-                v.view(b, s, n * d),
-                heads=self.num_heads,
-                transformer_options=transformer_options,
-            )
-        else:
-            end = kv_cache["end"]
-            new_end = end + s
-
-            # Roped K and plain V go into cache
-            kv_cache["k"][:, end:new_end] = k
-            kv_cache["v"][:, end:new_end] = v
-            kv_cache["end"] = new_end
-
-            x = optimized_attention(
-                q.view(b, s, n * d),
-                kv_cache["k"][:, :new_end].view(b, new_end, n * d),
-                kv_cache["v"][:, :new_end].view(b, new_end, n * d),
-                heads=self.num_heads,
-                transformer_options=transformer_options,
-            )
-
-        x = self.o(x)
-        return x
-
-
-class CausalWanAttentionBlock(WanAttentionBlock):
-    """Transformer block with KV-cached self-attention and cross-attention caching."""
-
-    def __init__(self, cross_attn_type, dim, ffn_dim, num_heads,
-                 window_size=(-1, -1), qk_norm=True, cross_attn_norm=False,
-                 eps=1e-6, operation_settings={}):
-        super().__init__(cross_attn_type, dim, ffn_dim, num_heads,
-                         window_size, qk_norm, cross_attn_norm, eps,
-                         operation_settings=operation_settings)
-        self.self_attn = CausalWanSelfAttention(
-            dim, num_heads, window_size, qk_norm, eps,
-            operation_settings=operation_settings)
-
-    def forward(self, x, e, freqs, context, context_img_len=257,
-                kv_cache=None, crossattn_cache=None, transformer_options={}):
-        if e.ndim < 4:
-            e = (comfy.model_management.cast_to(self.modulation, dtype=x.dtype, device=x.device) + e).chunk(6, dim=1)
-        else:
-            e = (comfy.model_management.cast_to(self.modulation, dtype=x.dtype, device=x.device).unsqueeze(0) + e).unbind(2)
-
-        # Self-attention with optional KV cache
-        x = x.contiguous()
-        y = self.self_attn(
-            torch.addcmul(repeat_e(e[0], x), self.norm1(x), 1 + repeat_e(e[1], x)),
-            freqs, kv_cache=kv_cache, transformer_options=transformer_options)
-        x = torch.addcmul(x, y, repeat_e(e[2], x))
-        del y
-
-        # Cross-attention with optional caching
-        if crossattn_cache is not None and crossattn_cache.get("is_init"):
-            q = self.cross_attn.norm_q(self.cross_attn.q(self.norm3(x)))
-            x_ca = optimized_attention(
-                q, crossattn_cache["k"], crossattn_cache["v"],
-                heads=self.num_heads, transformer_options=transformer_options)
-            x = x + self.cross_attn.o(x_ca)
-        else:
-            x = x + self.cross_attn(self.norm3(x), context, context_img_len=context_img_len, transformer_options=transformer_options)
-            if crossattn_cache is not None:
-                crossattn_cache["k"] = self.cross_attn.norm_k(self.cross_attn.k(context))
-                crossattn_cache["v"] = self.cross_attn.v(context)
-                crossattn_cache["is_init"] = True
-
-        # FFN
-        y = self.ffn(torch.addcmul(repeat_e(e[3], x), self.norm2(x), 1 + repeat_e(e[4], x)))
-        x = torch.addcmul(x, y, repeat_e(e[5], x))
-        return x
-
-
-class CausalWanModel(WanModel):
-    """
-    Wan 2.1 diffusion backbone with causal KV-cache support.
-
-    Same weight structure as WanModel -- loads identical state dicts.
-    Adds forward_block() for frame-by-frame autoregressive inference.
-    """
-
-    def __init__(self,
-                 model_type='t2v',
-                 patch_size=(1, 2, 2),
-                 text_len=512,
-                 in_dim=16,
-                 dim=2048,
-                 ffn_dim=8192,
-                 freq_dim=256,
-                 text_dim=4096,
-                 out_dim=16,
-                 num_heads=16,
-                 num_layers=32,
-                 window_size=(-1, -1),
-                 qk_norm=True,
-                 cross_attn_norm=True,
-                 eps=1e-6,
-                 image_model=None,
-                 device=None,
-                 dtype=None,
-                 operations=None):
-        super().__init__(
-            model_type=model_type, patch_size=patch_size, text_len=text_len,
-            in_dim=in_dim, dim=dim, ffn_dim=ffn_dim, freq_dim=freq_dim,
-            text_dim=text_dim, out_dim=out_dim, num_heads=num_heads,
-            num_layers=num_layers, window_size=window_size, qk_norm=qk_norm,
-            cross_attn_norm=cross_attn_norm, eps=eps, image_model=image_model,
-            wan_attn_block_class=CausalWanAttentionBlock,
-            device=device, dtype=dtype, operations=operations)
-
-    def forward_block(self, x, timestep, context, start_frame,
-                      kv_caches, crossattn_caches, clip_fea=None):
-        """
-        Forward one temporal block for autoregressive inference.
-
-        Args:
-            x: [B, C, block_frames, H, W] input latent for the current block
-            timestep: [B, block_frames] per-frame timesteps
-            context: [B, L, text_dim] raw text embeddings (pre-text_embedding)
-            start_frame: temporal frame index for RoPE offset
-            kv_caches: list of per-layer KV cache dicts
-            crossattn_caches: list of per-layer cross-attention cache dicts
-            clip_fea: optional CLIP features for I2V
-
-        Returns:
-            flow_pred: [B, C_out, block_frames, H, W] flow prediction
-        """
-        x = comfy.ldm.common_dit.pad_to_patch_size(x, self.patch_size)
-        bs, c, t, h, w = x.shape
-
-        x = self.patch_embedding(x.float()).to(x.dtype)
-        grid_sizes = x.shape[2:]
-        x = x.flatten(2).transpose(1, 2)
-
-        # Per-frame time embedding
-        e = self.time_embedding(
-            sinusoidal_embedding_1d(self.freq_dim, timestep.flatten()).to(dtype=x.dtype))
-        e = e.reshape(timestep.shape[0], -1, e.shape[-1])
-        e0 = self.time_projection(e).unflatten(2, (6, self.dim))
-
-        # Text embedding (reuses crossattn_cache after first block)
-        context = self.text_embedding(context)
-
-        context_img_len = None
-        if clip_fea is not None and self.img_emb is not None:
-            context_clip = self.img_emb(clip_fea)
-            context = torch.concat([context_clip, context], dim=1)
-            context_img_len = clip_fea.shape[-2]
-
-        # RoPE for current block's temporal position
-        freqs = self.rope_encode(t, h, w, t_start=start_frame, device=x.device, dtype=x.dtype)
-
-        # Transformer blocks
-        for i, block in enumerate(self.blocks):
-            x = block(x, e=e0, freqs=freqs, context=context,
-                      context_img_len=context_img_len,
-                      kv_cache=kv_caches[i],
-                      crossattn_cache=crossattn_caches[i])
-
-        # Head
-        x = self.head(x, e)
-
-        # Unpatchify
-        x = self.unpatchify(x, grid_sizes)
-        return x[:, :, :t, :h, :w]
-
-    def init_kv_caches(self, batch_size, max_seq_len, device, dtype):
-        """Create fresh KV caches for all layers."""
-        caches = []
-        for _ in range(self.num_layers):
-            caches.append({
-                "k": torch.zeros(batch_size, max_seq_len, self.num_heads, self.head_dim, device=device, dtype=dtype),
-                "v": torch.zeros(batch_size, max_seq_len, self.num_heads, self.head_dim, device=device, dtype=dtype),
-                "end": 0,
-            })
-        return caches
-
-    def init_crossattn_caches(self, batch_size, device, dtype):
-        """Create fresh cross-attention caches for all layers."""
-        caches = []
-        for _ in range(self.num_layers):
-            caches.append({"is_init": False})
-        return caches
-
-    def reset_kv_caches(self, kv_caches):
-        """Reset KV caches to empty (reuse allocated memory)."""
-        for cache in kv_caches:
-            cache["end"] = 0
-
-    def reset_crossattn_caches(self, crossattn_caches):
-        """Reset cross-attention caches."""
-        for cache in crossattn_caches:
-            cache["is_init"] = False
-
-    @property
-    def head_dim(self):
-        return self.dim // self.num_heads
-
-    def forward(self, x, timestep, context, clip_fea=None, time_dim_concat=None, transformer_options={}, **kwargs):
-        ar_state = transformer_options.get("ar_state")
-        if ar_state is not None:
-            bs = x.shape[0]
-            block_frames = x.shape[2]
-            t_per_frame = timestep.unsqueeze(1).expand(bs, block_frames)
-            return self.forward_block(
-                x=x, timestep=t_per_frame, context=context,
-                start_frame=ar_state["start_frame"],
-                kv_caches=ar_state["kv_caches"],
-                crossattn_caches=ar_state["crossattn_caches"],
-                clip_fea=clip_fea,
-            )
-
-        return super().forward(x, timestep, context, clip_fea=clip_fea,
-                               time_dim_concat=time_dim_concat,
-                               transformer_options=transformer_options, **kwargs)

comfy/model_base.py

@@ -42,7 +42,6 @@ import comfy.ldm.cosmos.predict2
 import comfy.ldm.lumina.model
 import comfy.ldm.wan.model
 import comfy.ldm.wan.model_animate
-import comfy.ldm.wan.ar_model
 import comfy.ldm.hunyuan3d.model
 import comfy.ldm.hidream.model
 import comfy.ldm.chroma.model
@@ -1366,13 +1365,6 @@ class WAN21(BaseModel):
         return out
 
 
-class WAN21_CausalAR(WAN21):
-    def __init__(self, model_config, model_type=ModelType.FLOW, device=None):
-        super(WAN21, self).__init__(model_config, model_type, device=device,
-                                    unet_model=comfy.ldm.wan.ar_model.CausalWanModel)
-        self.image_to_video = False
-
-
 class WAN21_Vace(WAN21):
     def __init__(self, model_config, model_type=ModelType.FLOW, image_to_video=False, device=None):
         super(WAN21, self).__init__(model_config, model_type, device=device, unet_model=comfy.ldm.wan.model.VaceWanModel)

comfy/model_management.py

@@ -721,13 +721,15 @@ def load_models_gpu(models, memory_required=0, force_patch_weights=False, minimu
     else:
         minimum_memory_required = max(inference_memory, minimum_memory_required + extra_reserved_memory())
 
-    models_temp = set()
+    # Order-preserving dedup. A plain set() would randomize iteration order across runs
+    models_temp = {}
     for m in models:
-        models_temp.add(m)
+        models_temp[m] = None
         for mm in m.model_patches_models():
-            models_temp.add(mm)
+            models_temp[mm] = None
 
-    models = models_temp
+    models = list(models_temp)
+    models.reverse()
 
     models_to_load = []
 

comfy/model_prefetch.py

@@ -37,7 +37,8 @@ def prefetch_queue_pop(queue, device, module):
     consumed = queue.pop(0)
     if consumed is not None:
         offload_stream, prefetch_state = consumed
-        offload_stream.wait_stream(comfy.model_management.current_stream(device))
+        if offload_stream is not None:
+            offload_stream.wait_stream(comfy.model_management.current_stream(device))
         _, comfy_modules = prefetch_state
         if comfy_modules is not None:
             cleanup_prefetched_modules(comfy_modules)

comfy/ops.py

@@ -253,6 +253,9 @@ def resolve_cast_module_with_vbar(s, dtype, device, bias_dtype, compute_dtype, w
     if bias is not None:
         bias = post_cast(s, "bias", bias, bias_dtype, prefetch["resident"], update_weight)
 
+    if prefetch["signature"] is not None:
+        prefetch["resident"] = True
+
     return weight, bias
 
 

comfy/sampler_helpers.py

@@ -89,7 +89,8 @@ def get_additional_models(conds, dtype):
         gligen += get_models_from_cond(conds[k], "gligen")
         add_models += get_models_from_cond(conds[k], "additional_models")
 
-    control_nets = set(cnets)
+    # Order-preserving dedup. A plain set() would randomize iteration order across runs
+    control_nets = list(dict.fromkeys(cnets))
 
     inference_memory = 0
     control_models = []

comfy/supported_models.py

@@ -1167,25 +1167,6 @@ class WAN21_T2V(supported_models_base.BASE):
         t5_detect = comfy.text_encoders.sd3_clip.t5_xxl_detect(state_dict, "{}umt5xxl.transformer.".format(pref))
         return supported_models_base.ClipTarget(comfy.text_encoders.wan.WanT5Tokenizer, comfy.text_encoders.wan.te(**t5_detect))
 
-class WAN21_CausalAR_T2V(WAN21_T2V):
-    unet_config = {
-        "image_model": "wan2.1",
-        "model_type": "t2v",
-        "causal_ar": True,
-    }
-
-    sampling_settings = {
-        "shift": 5.0,
-    }
-
-    def __init__(self, unet_config):
-        super().__init__(unet_config)
-        self.unet_config.pop("causal_ar", None)
-
-    def get_model(self, state_dict, prefix="", device=None):
-        return model_base.WAN21_CausalAR(self, device=device)
-
-
 class WAN21_I2V(WAN21_T2V):
     unet_config = {
         "image_model": "wan2.1",
@@ -1948,7 +1929,6 @@ models = [
     ZImage,
     Lumina2,
     WAN22_T2V,
-    WAN21_CausalAR_T2V,
     WAN21_T2V,
     WAN21_I2V,
     WAN21_FunControl2V,

comfy_api/feature_flags.py

@@ -5,12 +5,95 @@ This module handles capability negotiation between frontend and backend,
 allowing graceful protocol evolution while maintaining backward compatibility.
 """
 
-from typing import Any
+import logging
+from typing import Any, TypedDict
 
 from comfy.cli_args import args
 
+
+class FeatureFlagInfo(TypedDict):
+    type: str
+    default: Any
+    description: str
+
+
+# Registry of known CLI-settable feature flags.
+# Launchers can query this via --list-feature-flags to discover valid flags.
+CLI_FEATURE_FLAG_REGISTRY: dict[str, FeatureFlagInfo] = {
+    "show_signin_button": {
+        "type": "bool",
+        "default": False,
+        "description": "Show the sign-in button in the frontend even when not signed in",
+    },
+}
+
+
+def _coerce_bool(v: str) -> bool:
+    """Strict bool coercion: only 'true'/'false' (case-insensitive).
+
+    Anything else raises ValueError so the caller can warn and drop the flag,
+    rather than silently treating typos like 'ture' or 'yes' as False.
+    """
+    lower = v.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+    raise ValueError(f"expected 'true' or 'false', got {v!r}")
+
+
+_COERCE_FNS: dict[str, Any] = {
+    "bool": _coerce_bool,
+    "int": lambda v: int(v),
+    "float": lambda v: float(v),
+}
+
+
+def _coerce_flag_value(key: str, raw_value: str) -> Any:
+    """Coerce a raw string value using the registry type, or keep as string.
+
+    Returns the raw string if the key is unregistered or the type is unknown.
+    Raises ValueError/TypeError if the key is registered with a known type but
+    the value cannot be coerced; callers are expected to warn and drop the flag.
+    """
+    info = CLI_FEATURE_FLAG_REGISTRY.get(key)
+    if info is None:
+        return raw_value
+    coerce = _COERCE_FNS.get(info["type"])
+    if coerce is None:
+        return raw_value
+    return coerce(raw_value)
+
+
+def _parse_cli_feature_flags() -> dict[str, Any]:
+    """Parse --feature-flag key=value pairs from CLI args into a dict.
+
+    Items without '=' default to the value 'true' (bare flag form).
+    Flags whose value cannot be coerced to the registered type are dropped
+    with a warning, so a typo like '--feature-flag some_bool=ture' does not
+    silently take effect as the wrong value.
+    """
+    result: dict[str, Any] = {}
+    for item in getattr(args, "feature_flag", []):
+        key, sep, raw_value = item.partition("=")
+        key = key.strip()
+        if not key:
+            continue
+        if not sep:
+            raw_value = "true"
+        try:
+            result[key] = _coerce_flag_value(key, raw_value.strip())
+        except (ValueError, TypeError) as e:
+            info = CLI_FEATURE_FLAG_REGISTRY.get(key, {})
+            logging.warning(
+                "Could not coerce --feature-flag %s=%r to %s (%s); dropping flag.",
+                key, raw_value.strip(), info.get("type", "?"), e,
+            )
+    return result
+
+
 # Default server capabilities
-SERVER_FEATURE_FLAGS: dict[str, Any] = {
+_CORE_FEATURE_FLAGS: dict[str, Any] = {
     "supports_preview_metadata": True,
     "max_upload_size": args.max_upload_size * 1024 * 1024, # Convert MB to bytes
     "extension": {"manager": {"supports_v4": True}},
@@ -18,6 +101,11 @@ SERVER_FEATURE_FLAGS: dict[str, Any] = {
     "assets": args.enable_assets,
 }
 
+# CLI-provided flags cannot overwrite core flags
+_cli_flags = {k: v for k, v in _parse_cli_feature_flags().items() if k not in _CORE_FEATURE_FLAGS}
+
+SERVER_FEATURE_FLAGS: dict[str, Any] = {**_CORE_FEATURE_FLAGS, **_cli_flags}
+
 
 def get_connection_feature(
     sockets_metadata: dict[str, dict[str, Any]],

comfy_api_nodes/nodes_sora.py

@@ -33,7 +33,7 @@ class OpenAIVideoSora2(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="OpenAIVideoSora2",
-            display_name="OpenAI Sora - Video (Deprecated)",
+            display_name="OpenAI Sora - Video (DEPRECATED)",
             category="api node/video/Sora",
             description=(
                 "OpenAI video and audio generation.\n\n"

comfy_extras/nodes_ar_video.py

@@ -1,136 +0,0 @@
-"""
-ComfyUI nodes for autoregressive video generation (Causal Forcing, Self-Forcing, etc.).
-  - EmptyARVideoLatent: create 5D [B, C, T, H, W] video latent tensors
-  - SamplerARVideo: SAMPLER for the block-by-block autoregressive denoising loop
-  - ARVideoI2V: image-to-video conditioning for AR models (seeds KV cache with start image)
-"""
-
-import torch
-from typing_extensions import override
-
-import comfy.model_management
-import comfy.samplers
-import comfy.utils
-from comfy_api.latest import ComfyExtension, io
-
-
-class EmptyARVideoLatent(io.ComfyNode):
-    @classmethod
-    def define_schema(cls):
-        return io.Schema(
-            node_id="EmptyARVideoLatent",
-            category="latent/video",
-            inputs=[
-                io.Int.Input("width", default=832, min=16, max=8192, step=16),
-                io.Int.Input("height", default=480, min=16, max=8192, step=16),
-                io.Int.Input("length", default=81, min=1, max=1024, step=4),
-                io.Int.Input("batch_size", default=1, min=1, max=64),
-            ],
-            outputs=[
-                io.Latent.Output(display_name="LATENT"),
-            ],
-        )
-
-    @classmethod
-    def execute(cls, width, height, length, batch_size) -> io.NodeOutput:
-        lat_t = ((length - 1) // 4) + 1
-        latent = torch.zeros(
-            [batch_size, 16, lat_t, height // 8, width // 8],
-            device=comfy.model_management.intermediate_device(),
-        )
-        return io.NodeOutput({"samples": latent})
-
-
-class SamplerARVideo(io.ComfyNode):
-    """Sampler for autoregressive video models (Causal Forcing, Self-Forcing).
-
-    All AR-loop parameters are owned by this node so they live in the workflow.
-    Add new widgets here as the AR sampler grows new options.
-    """
-
-    @classmethod
-    def define_schema(cls):
-        return io.Schema(
-            node_id="SamplerARVideo",
-            display_name="Sampler AR Video",
-            category="sampling/custom_sampling/samplers",
-            inputs=[
-                io.Int.Input(
-                    "num_frame_per_block",
-                    default=1, min=1, max=64,
-                    tooltip="Frames per autoregressive block. 1 = framewise, "
-                            "3 = chunkwise. Must match the checkpoint's training mode.",
-                ),
-            ],
-            outputs=[io.Sampler.Output()],
-        )
-
-    @classmethod
-    def execute(cls, num_frame_per_block) -> io.NodeOutput:
-        extra_options = {
-            "num_frame_per_block": num_frame_per_block,
-        }
-        return io.NodeOutput(comfy.samplers.ksampler("ar_video", extra_options))
-
-
-class ARVideoI2V(io.ComfyNode):
-    """Image-to-video setup for AR video models (Causal Forcing, Self-Forcing).
-
-    VAE-encodes the start image and stores it in the model's transformer_options
-    so that sample_ar_video can seed the KV cache before denoising.
-    Uses the same T2V model checkpoint -- no separate I2V architecture needed.
-    """
-
-    @classmethod
-    def define_schema(cls):
-        return io.Schema(
-            node_id="ARVideoI2V",
-            category="conditioning/video_models",
-            inputs=[
-                io.Model.Input("model"),
-                io.Vae.Input("vae"),
-                io.Image.Input("start_image"),
-                io.Int.Input("width", default=832, min=16, max=8192, step=16),
-                io.Int.Input("height", default=480, min=16, max=8192, step=16),
-                io.Int.Input("length", default=81, min=1, max=1024, step=4),
-                io.Int.Input("batch_size", default=1, min=1, max=64),
-            ],
-            outputs=[
-                io.Model.Output(display_name="MODEL"),
-                io.Latent.Output(display_name="LATENT"),
-            ],
-        )
-
-    @classmethod
-    def execute(cls, model, vae, start_image, width, height, length, batch_size) -> io.NodeOutput:
-        start_image = comfy.utils.common_upscale(
-            start_image[:1].movedim(-1, 1), width, height, "bilinear", "center"
-        ).movedim(1, -1)
-
-        initial_latent = vae.encode(start_image[:, :, :, :3])
-
-        m = model.clone()
-        to = m.model_options.setdefault("transformer_options", {})
-        ar_cfg = to.setdefault("ar_config", {})
-        ar_cfg["initial_latent"] = initial_latent
-
-        lat_t = ((length - 1) // 4) + 1
-        latent = torch.zeros(
-            [batch_size, 16, lat_t, height // 8, width // 8],
-            device=comfy.model_management.intermediate_device(),
-        )
-        return io.NodeOutput(m, {"samples": latent})
-
-
-class ARVideoExtension(ComfyExtension):
-    @override
-    async def get_node_list(self) -> list[type[io.ComfyNode]]:
-        return [
-            EmptyARVideoLatent,
-            SamplerARVideo,
-            ARVideoI2V,
-        ]
-
-
-async def comfy_entrypoint() -> ARVideoExtension:
-    return ARVideoExtension()

comfy_extras/nodes_frame_interpolation.py

@@ -78,7 +78,7 @@ class FrameInterpolate(io.ComfyNode):
         return io.Schema(
             node_id="FrameInterpolate",
             display_name="Frame Interpolate",
-            category="image/video",
+            category="video",
             search_aliases=["rife", "film", "frame interpolation", "slow motion", "interpolate frames", "vfi"],
             inputs=[
                 FrameInterpolationModel.Input("interp_model"),

comfy_extras/nodes_image_compare.py

@@ -11,7 +11,7 @@ class ImageCompare(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="ImageCompare",
-            display_name="Image Compare",
+            display_name="Compare Images",
             description="Compares two images side by side with a slider.",
             category="image",
             essentials_category="Image Tools",

comfy_extras/nodes_images.py

@@ -24,7 +24,7 @@ class ImageCrop(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageCrop",
             search_aliases=["trim"],
-            display_name="Image Crop (Deprecated)",
+            display_name="Crop Image (DEPRECATED)",
             category="image/transform",
             is_deprecated=True,
             essentials_category="Image Tools",
@@ -56,7 +56,7 @@ class ImageCropV2(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageCropV2",
             search_aliases=["trim"],
-            display_name="Image Crop",
+            display_name="Crop Image",
             category="image/transform",
             essentials_category="Image Tools",
             has_intermediate_output=True,
@@ -109,6 +109,7 @@ class RepeatImageBatch(IO.ComfyNode):
         return IO.Schema(
             node_id="RepeatImageBatch",
             search_aliases=["duplicate image", "clone image"],
+            display_name="Repeat Image Batch",
             category="image/batch",
             inputs=[
                 IO.Image.Input("image"),
@@ -131,6 +132,7 @@ class ImageFromBatch(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageFromBatch",
             search_aliases=["select image", "pick from batch", "extract image"],
+            display_name="Get Image from Batch",
             category="image/batch",
             inputs=[
                 IO.Image.Input("image"),
@@ -157,7 +159,8 @@ class ImageAddNoise(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageAddNoise",
             search_aliases=["film grain"],
-            category="image",
+            display_name="Add Noise to Image",
+            category="image/postprocessing",
             inputs=[
                 IO.Image.Input("image"),
                 IO.Int.Input(
@@ -259,7 +262,7 @@ class ImageStitch(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageStitch",
             search_aliases=["combine images", "join images", "concatenate images", "side by side"],
-            display_name="Image Stitch",
+            display_name="Stitch Images",
             description="Stitches image2 to image1 in the specified direction.\n"
             "If image2 is not provided, returns image1 unchanged.\n"
             "Optional spacing can be added between images.",
@@ -434,6 +437,7 @@ class ResizeAndPadImage(IO.ComfyNode):
         return IO.Schema(
             node_id="ResizeAndPadImage",
             search_aliases=["fit to size"],
+            display_name="Resize And Pad Image",
             category="image/transform",
             inputs=[
                 IO.Image.Input("image"),
@@ -485,6 +489,7 @@ class SaveSVGNode(IO.ComfyNode):
         return IO.Schema(
             node_id="SaveSVGNode",
             search_aliases=["export vector", "save vector graphics"],
+            display_name="Save SVG",
             description="Save SVG files on disk.",
             category="image/save",
             inputs=[
@@ -591,7 +596,7 @@ class ImageRotate(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="ImageRotate",
-            display_name="Image Rotate",
+            display_name="Rotate Image",
             search_aliases=["turn", "flip orientation"],
             category="image/transform",
             essentials_category="Image Tools",
@@ -624,6 +629,7 @@ class ImageFlip(IO.ComfyNode):
         return IO.Schema(
             node_id="ImageFlip",
             search_aliases=["mirror", "reflect"],
+            display_name="Flip Image",
             category="image/transform",
             inputs=[
                 IO.Image.Input("image"),
@@ -650,6 +656,7 @@ class ImageScaleToMaxDimension(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="ImageScaleToMaxDimension",
+            display_name="Scale Image to Max Dimension",
             category="image/upscaling",
             inputs=[
                 IO.Image.Input("image"),

comfy_extras/nodes_mask.py

@@ -80,7 +80,8 @@ class ImageCompositeMasked(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="ImageCompositeMasked",
-            search_aliases=["paste image", "overlay", "layer"],
+            search_aliases=["overlay", "layer", "paste image", "images composition"],
+            display_name="Image Composite Masked",
             category="image",
             inputs=[
                 IO.Image.Input("destination"),
@@ -201,6 +202,7 @@ class InvertMask(IO.ComfyNode):
         return IO.Schema(
             node_id="InvertMask",
             search_aliases=["reverse mask", "flip mask"],
+            display_name="Invert Mask",
             category="mask",
             inputs=[
                 IO.Mask.Input("mask"),
@@ -222,6 +224,7 @@ class CropMask(IO.ComfyNode):
         return IO.Schema(
             node_id="CropMask",
             search_aliases=["cut mask", "extract mask region", "mask slice"],
+            display_name="Crop Mask",
             category="mask",
             inputs=[
                 IO.Mask.Input("mask"),
@@ -247,7 +250,8 @@ class MaskComposite(IO.ComfyNode):
     def define_schema(cls):
         return IO.Schema(
             node_id="MaskComposite",
-            search_aliases=["combine masks", "blend masks", "layer masks"],
+            search_aliases=["combine masks", "blend masks", "layer masks", "masks composition"],
+            display_name="Combine Masks",
             category="mask",
             inputs=[
                 IO.Mask.Input("destination"),
@@ -298,6 +302,7 @@ class FeatherMask(IO.ComfyNode):
         return IO.Schema(
             node_id="FeatherMask",
             search_aliases=["soft edge mask", "blur mask edges", "gradient mask edge"],
+            display_name="Feather Mask",
             category="mask",
             inputs=[
                 IO.Mask.Input("mask"),

comfy_extras/nodes_morphology.py

@@ -59,7 +59,8 @@ class ImageRGBToYUV(io.ComfyNode):
         return io.Schema(
             node_id="ImageRGBToYUV",
             search_aliases=["color space conversion"],
-            category="image/batch",
+            display_name="Image RGB to YUV",
+            category="image/color",
             inputs=[
                 io.Image.Input("image"),
             ],
@@ -81,7 +82,8 @@ class ImageYUVToRGB(io.ComfyNode):
         return io.Schema(
             node_id="ImageYUVToRGB",
             search_aliases=["color space conversion"],
-            category="image/batch",
+            display_name="Image YUV to RGB",
+            category="image/color",
             inputs=[
                 io.Image.Input("Y"),
                 io.Image.Input("U"),

comfy_extras/nodes_post_processing.py

@@ -20,7 +20,8 @@ class Blend(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="ImageBlend",
-            display_name="Image Blend",
+            search_aliases=["mix images"],
+            display_name="Blend Images",
             category="image/postprocessing",
             essentials_category="Image Tools",
             inputs=[
@@ -224,6 +225,7 @@ class ImageScaleToTotalPixels(io.ComfyNode):
     def define_schema(cls):
         return io.Schema(
             node_id="ImageScaleToTotalPixels",
+            display_name="Scale Image to Total Pixels",
             category="image/upscaling",
             inputs=[
                 io.Image.Input("image"),
@@ -568,7 +570,7 @@ class BatchImagesNode(io.ComfyNode):
         return io.Schema(
             node_id="BatchImagesNode",
             display_name="Batch Images",
-            category="image",
+            category="image/batch",
             essentials_category="Image Tools",
             search_aliases=["batch", "image batch", "batch images", "combine images", "merge images", "stack images"],
             inputs=[

comfy_extras/nodes_video.py

@@ -17,7 +17,8 @@ class SaveWEBM(io.ComfyNode):
         return io.Schema(
             node_id="SaveWEBM",
             search_aliases=["export webm"],
-            category="image/video",
+            display_name="Save WEBM",
+            category="video",
             is_experimental=True,
             inputs=[
                 io.Image.Input("images"),
@@ -72,7 +73,7 @@ class SaveVideo(io.ComfyNode):
             node_id="SaveVideo",
             search_aliases=["export video"],
             display_name="Save Video",
-            category="image/video",
+            category="video",
             essentials_category="Basics",
             description="Saves the input images to your ComfyUI output directory.",
             inputs=[
@@ -121,7 +122,7 @@ class CreateVideo(io.ComfyNode):
             node_id="CreateVideo",
             search_aliases=["images to video"],
             display_name="Create Video",
-            category="image/video",
+            category="video",
             description="Create a video from images.",
             inputs=[
                 io.Image.Input("images", tooltip="The images to create a video from."),
@@ -146,7 +147,7 @@ class GetVideoComponents(io.ComfyNode):
             node_id="GetVideoComponents",
             search_aliases=["extract frames", "split video", "video to images", "demux"],
             display_name="Get Video Components",
-            category="image/video",
+            category="video",
             description="Extracts all components from a video: frames, audio, and framerate.",
             inputs=[
                 io.Video.Input("video", tooltip="The video to extract components from."),
@@ -174,7 +175,7 @@ class LoadVideo(io.ComfyNode):
             node_id="LoadVideo",
             search_aliases=["import video", "open video", "video file"],
             display_name="Load Video",
-            category="image/video",
+            category="video",
             essentials_category="Basics",
             inputs=[
                 io.Combo.Input("file", options=sorted(files), upload=io.UploadType.video),
@@ -216,7 +217,7 @@ class VideoSlice(io.ComfyNode):
                 "frame load cap",
                 "start time",
             ],
-            category="image/video",
+            category="video",
             essentials_category="Video Tools",
             inputs=[
                 io.Video.Input("video"),

main.py

@@ -1,13 +1,21 @@
 import comfy.options
 comfy.options.enable_args_parsing()
 
+from comfy.cli_args import args
+
+if args.list_feature_flags:
+    import json
+    from comfy_api.feature_flags import CLI_FEATURE_FLAG_REGISTRY
+    print(json.dumps(CLI_FEATURE_FLAG_REGISTRY, indent=2))  # noqa: T201
+    raise SystemExit(0)
+
 import os
 import importlib.util
 import shutil
 import importlib.metadata
 import folder_paths
 import time
-from comfy.cli_args import args, enables_dynamic_vram
+from comfy.cli_args import enables_dynamic_vram
 from app.logger import setup_logger
 setup_logger(log_level=args.verbose, use_stdout=args.log_stdout)
 

nodes.py

@@ -1887,7 +1887,7 @@ class ImageInvert:
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "invert"
 
-    CATEGORY = "image"
+    CATEGORY = "image/color"
 
     def invert(self, image):
         s = 1.0 - image
@@ -1903,7 +1903,7 @@ class ImageBatch:
     RETURN_TYPES = ("IMAGE",)
     FUNCTION = "batch"
 
-    CATEGORY = "image"
+    CATEGORY = "image/batch"
     DEPRECATED = True
 
     def batch(self, image1, image2):
@@ -1960,7 +1960,7 @@ class ImagePadForOutpaint:
     RETURN_TYPES = ("IMAGE", "MASK")
     FUNCTION = "expand_image"
 
-    CATEGORY = "image"
+    CATEGORY = "image/transform"
 
     def expand_image(self, image, left, top, right, bottom, feathering):
         d1, d2, d3, d4 = image.size()
@@ -2103,7 +2103,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "ConditioningSetArea": "Conditioning (Set Area)",
     "ConditioningSetAreaPercentage": "Conditioning (Set Area with Percentage)",
     "ConditioningSetMask": "Conditioning (Set Mask)",
-    "ControlNetApply": "Apply ControlNet (OLD)",
+    "ControlNetApply": "Apply ControlNet (DEPRECATED)",
     "ControlNetApplyAdvanced": "Apply ControlNet",
     # Latent
     "VAEEncodeForInpaint": "VAE Encode (for Inpainting)",
@@ -2121,6 +2121,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "LatentFromBatch" : "Latent From Batch",
     "RepeatLatentBatch": "Repeat Latent Batch",
     # Image
+    "EmptyImage": "Empty Image",
     "SaveImage": "Save Image",
     "PreviewImage": "Preview Image",
     "LoadImage": "Load Image",
@@ -2128,15 +2129,15 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "LoadImageOutput": "Load Image (from Outputs)",
     "ImageScale": "Upscale Image",
     "ImageScaleBy": "Upscale Image By",
-    "ImageInvert": "Invert Image",
+    "ImageInvert": "Invert Image Colors",
     "ImagePadForOutpaint": "Pad Image for Outpainting",
-    "ImageBatch": "Batch Images",
-    "ImageCrop": "Image Crop",
-    "ImageStitch": "Image Stitch",
-    "ImageBlend": "Image Blend",
-    "ImageBlur": "Image Blur",
-    "ImageQuantize": "Image Quantize",
-    "ImageSharpen": "Image Sharpen",
+    "ImageBatch": "Batch Images (DEPRECATED)",
+    "ImageCrop": "Crop Image",
+    "ImageStitch": "Stitch Images",
+    "ImageBlend": "Blend Images",
+    "ImageBlur": "Blur Image",
+    "ImageQuantize": "Quantize Image",
+    "ImageSharpen": "Sharpen Image",
     "ImageScaleToTotalPixels": "Scale Image to Total Pixels",
     "GetImageSize": "Get Image Size",
     # _for_testing
@@ -2411,7 +2412,6 @@ async def init_builtin_extra_nodes():
         "nodes_nop.py",
         "nodes_kandinsky5.py",
         "nodes_wanmove.py",
-        "nodes_ar_video.py",
         "nodes_image_compare.py",
         "nodes_zimage.py",
         "nodes_glsl.py",

openapi.yaml

@@ -1999,6 +1999,26 @@ components:
           items:
             type: string
           description: List of node IDs to execute (partial graph execution)
+        workflow_id:
+          type: string
+          format: uuid
+          nullable: true
+          x-runtime: [cloud]
+          description: |
+            UUID identifying a hosted-cloud workflow entity to associate with this
+            job. Local ComfyUI doesn't track workflow entities and returns `null`
+            (or omits the field). The `x-runtime: [cloud]` extension marks this
+            as populated only by the hosted-cloud runtime; absence of the tag
+            means a field is populated by all runtimes.
+        workflow_version_id:
+          type: string
+          format: uuid
+          nullable: true
+          x-runtime: [cloud]
+          description: |
+            UUID identifying a hosted-cloud workflow version to associate with
+            this job. Local ComfyUI returns `null` (or omits the field). See
+            `workflow_id` above for `x-runtime` semantics.
 
     PromptResponse:
       type: object
@@ -2347,7 +2367,12 @@ components:
           description: Device type (cuda, mps, cpu, etc.)
         index:
           type: number
-          description: Device index
+          nullable: true
+          description: |
+            Device index within its type (e.g. CUDA ordinal for `cuda:0`,
+            `cuda:1`). `null` for devices with no index, including the CPU
+            device returned in `--cpu` mode (PyTorch's `torch.device('cpu').index`
+            is `None`).
         vram_total:
           type: number
           description: Total VRAM in bytes
@@ -2503,7 +2528,18 @@ components:
           description: Alternative search terms for finding this node
         essentials_category:
           type: string
-          description: Category override used by the essentials pack
+          nullable: true
+          description: |
+            Category override used by the essentials pack. The
+            `essentials_category` key may be present with a string value,
+            present and `null`, or absent entirely:
+
+            - V1 nodes: `essentials_category` is **omitted** when the node
+              class doesn't define an `ESSENTIALS_CATEGORY` attribute, and
+              **`null`** if the attribute is explicitly set to `None`.
+            - V3 nodes (`comfy_api.latest.io`): `essentials_category` is
+              **always present**, and **`null`** for nodes whose `Schema`
+              doesn't populate it.
 
     # -------------------------------------------------------------------
     # Models

tests-unit/feature_flags_test.py

@@ -1,10 +1,15 @@
 """Tests for feature flags functionality."""
 
+import pytest
+
 from comfy_api.feature_flags import (
     get_connection_feature,
     supports_feature,
     get_server_features,
+    CLI_FEATURE_FLAG_REGISTRY,
     SERVER_FEATURE_FLAGS,
+    _coerce_flag_value,
+    _parse_cli_feature_flags,
 )
 
 
@@ -96,3 +101,83 @@ class TestFeatureFlags:
         result = get_connection_feature(sockets_metadata, "sid1", "any_feature")
         assert result is False
         assert supports_feature(sockets_metadata, "sid1", "any_feature") is False
+
+
+class TestCoerceFlagValue:
+    """Test suite for _coerce_flag_value."""
+
+    def test_registered_bool_true(self):
+        assert _coerce_flag_value("show_signin_button", "true") is True
+        assert _coerce_flag_value("show_signin_button", "True") is True
+
+    def test_registered_bool_false(self):
+        assert _coerce_flag_value("show_signin_button", "false") is False
+        assert _coerce_flag_value("show_signin_button", "FALSE") is False
+
+    def test_unregistered_key_stays_string(self):
+        assert _coerce_flag_value("unknown_flag", "true") == "true"
+        assert _coerce_flag_value("unknown_flag", "42") == "42"
+
+    def test_bool_typo_raises(self):
+        """Strict bool: typos like 'ture' or 'yes' must raise so the flag can be dropped."""
+        with pytest.raises(ValueError):
+            _coerce_flag_value("show_signin_button", "ture")
+        with pytest.raises(ValueError):
+            _coerce_flag_value("show_signin_button", "yes")
+        with pytest.raises(ValueError):
+            _coerce_flag_value("show_signin_button", "1")
+        with pytest.raises(ValueError):
+            _coerce_flag_value("show_signin_button", "")
+
+    def test_failed_int_coercion_raises(self, monkeypatch):
+        """Malformed values for typed flags must raise; caller decides what to do."""
+        monkeypatch.setitem(
+            CLI_FEATURE_FLAG_REGISTRY,
+            "test_int_flag",
+            {"type": "int", "default": 0, "description": "test"},
+        )
+        with pytest.raises(ValueError):
+            _coerce_flag_value("test_int_flag", "not_a_number")
+
+
+class TestParseCliFeatureFlags:
+    """Test suite for _parse_cli_feature_flags."""
+
+    def test_single_flag(self, monkeypatch):
+        monkeypatch.setattr("comfy_api.feature_flags.args", type("Args", (), {"feature_flag": ["show_signin_button=true"]})())
+        result = _parse_cli_feature_flags()
+        assert result == {"show_signin_button": True}
+
+    def test_missing_equals_defaults_to_true(self, monkeypatch):
+        """Bare flag without '=' is treated as the string 'true' (and coerced if registered)."""
+        monkeypatch.setattr("comfy_api.feature_flags.args", type("Args", (), {"feature_flag": ["show_signin_button", "valid=1"]})())
+        result = _parse_cli_feature_flags()
+        assert result == {"show_signin_button": True, "valid": "1"}
+
+    def test_empty_key_skipped(self, monkeypatch):
+        monkeypatch.setattr("comfy_api.feature_flags.args", type("Args", (), {"feature_flag": ["=value", "valid=1"]})())
+        result = _parse_cli_feature_flags()
+        assert result == {"valid": "1"}
+
+    def test_invalid_bool_value_dropped(self, monkeypatch, caplog):
+        """A typo'd bool value must be dropped entirely, not silently set to False
+        and not stored as a raw string. A warning must be logged."""
+        monkeypatch.setattr(
+            "comfy_api.feature_flags.args",
+            type("Args", (), {"feature_flag": ["show_signin_button=ture", "valid=1"]})(),
+        )
+        with caplog.at_level("WARNING"):
+            result = _parse_cli_feature_flags()
+        assert result == {"valid": "1"}
+        assert "show_signin_button" not in result
+        assert any("show_signin_button" in r.message and "drop" in r.message.lower() for r in caplog.records)
+
+
+class TestCliFeatureFlagRegistry:
+    """Test suite for the CLI feature flag registry."""
+
+    def test_registry_entries_have_required_fields(self):
+        for key, info in CLI_FEATURE_FLAG_REGISTRY.items():
+            assert "type" in info, f"{key} missing 'type'"
+            assert "default" in info, f"{key} missing 'default'"
+            assert "description" in info, f"{key} missing 'description'"