feat(comfyui): comfyui_interrupt_queue v1.1.0 — clear_pending + cleared/queue_remaining + tests

Alinea la funcion al contrato de control de cola (punto 3 del roadmap ComfyUI):
- firma keyword-only: clear_pending (vacia pendientes con POST /queue {clear:true}) + timeout
- output {ok, interrupted, cleared, queue_remaining, error}; GET /queue al final
- no lanza en fallo de red: degrada a {ok:False, error}
- test con mock HTTP local (golden + clear + cola vacia + error path), 4/4 verde
- .md autosuficiente con gotchas + capability growth log

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/ml/comfyui_interrupt_queue.md

@@ -3,10 +3,10 @@ name: comfyui_interrupt_queue
 kind: function
 lang: py
 domain: ml
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
-signature: "def comfyui_interrupt_queue(server: str = \"127.0.0.1:8188\") -> dict"
-description: "Corta la generacion en curso de ComfyUI (POST /interrupt) y devuelve el estado de la cola (GET /queue). Devuelve {ok, interrupted, queue_running, queue_pending, error}. NO lanza excepcion en fallo de red: degrada a {ok: False, error}. /interrupt corta solo el prompt en ejecucion, no vacia los pendientes. Impura: HTTP POST + GET, solo stdlib (urllib, json)."
+signature: "def comfyui_interrupt_queue(*, clear_pending: bool = False, server: str = \"127.0.0.1:8188\", timeout: float = 10.0) -> dict"
+description: "Corta la generacion en curso de ComfyUI (POST /interrupt) y, si clear_pending=True, vacia ademas la cola de pendientes (POST /queue {\"clear\":true}). Consulta GET /queue al final para reportar queue_remaining. Devuelve {ok, interrupted, cleared, queue_remaining, error}. NO lanza excepcion en fallo de red: degrada a {ok: False, error}. /interrupt corta solo el prompt en ejecucion, no vacia los pendientes salvo clear_pending. Impura: HTTP POST + GET, solo stdlib (urllib, json)."
 tags: [comfyui, ml, queue, interrupt, control, http]
 uses_functions: []
 uses_types: []
@@ -15,12 +15,16 @@ returns_optional: false
 error_type: "error_go_core"
 imports: []
 params:
+  - name: clear_pending
+    desc: "keyword-only. Si True, ademas de cortar el prompt en ejecucion vacia la cola de pendientes con POST /queue {\"clear\":true}. Default False."
   - name: server
-    desc: "host:port del servidor ComfyUI sin esquema (default '127.0.0.1:8188')."
-output: "dict con ok (bool, True si interrupt + lectura de cola OK), interrupted (bool, True si POST /interrupt respondio), queue_running (int, prompts ejecutandose), queue_pending (int, prompts encolados), error (str, vacio si todo OK)."
-tested: false
-tests: []
-test_file_path: ""
+    desc: "keyword-only. host:port del servidor ComfyUI sin esquema (default '127.0.0.1:8188')."
+  - name: timeout
+    desc: "keyword-only. Timeout de cada peticion HTTP en segundos (default 10.0)."
+output: "dict con ok (bool, True si interrupt + clear (si se pidio) + lectura de cola OK), interrupted (bool, True si POST /interrupt respondio), cleared (bool, True si clear_pending y POST /queue {clear:true} respondio; False si no se pidio o fallo), queue_remaining (int, queue_running + queue_pending tras la operacion), error (str, vacio si todo OK)."
+tested: true
+tests: ["test_interrumpe_sin_vaciar", "test_clear_pending_vacia_cola", "test_clear_pending_cola_vacia_no_rompe", "test_servidor_caido_no_lanza"]
+test_file_path: "python/functions/ml/tests/test_comfyui_interrupt_queue.py"
 file_path: "python/functions/ml/comfyui_interrupt_queue.py"
 ---
 
@@ -31,30 +35,47 @@ import sys, os
 sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
 from ml.comfyui_interrupt_queue import comfyui_interrupt_queue
 
+# Solo cortar el prompt en ejecucion (los pendientes siguen):
 res = comfyui_interrupt_queue()
-# {'ok': True, 'interrupted': True, 'queue_running': 0, 'queue_pending': 0, 'error': ''}
-if res["ok"] and res["interrupted"]:
-    print(f"cortado; pendientes en cola: {res['queue_pending']}")
+# {'ok': True, 'interrupted': True, 'cleared': False, 'queue_remaining': 3, 'error': ''}
+
+# Cortar el actual Y vaciar los pendientes de golpe:
+res = comfyui_interrupt_queue(clear_pending=True)
+# {'ok': True, 'interrupted': True, 'cleared': True, 'queue_remaining': 0, 'error': ''}
+if res["ok"]:
+    print(f"cortado; quedan {res['queue_remaining']} en cola")
 ```
 
-O lanzable directo con: `./fn run comfyui_interrupt_queue`.
+O lanzable directo: `./fn run comfyui_interrupt_queue` · `./fn run comfyui_interrupt_queue --clear`.
 
 ## Cuando usarla
 
 Para abortar una generacion que se esta tomando demasiado, que tira de mas VRAM de
-la prevista, o tras encolar por error un workflow pesado. Tambien para inspeccionar
-de un vistazo cuanto queda en cola (`queue_running` / `queue_pending`) sin parsear
-el JSON de /queue a mano. Es el freno de mano del round-trip build -> submit -> wait.
+la prevista, o tras encolar por error un workflow pesado. Con `clear_pending=True`
+es el freno de mano completo: corta el actual y borra todo lo encolado en una sola
+llamada (sin tener que encadenar `comfyui_queue_manage("clear")` despues). Tras la
+operacion `queue_remaining` dice de un vistazo cuanto queda en cola.
 
 ## Gotchas
 
-- `/interrupt` corta SOLO el prompt en ejecucion; los pendientes (`queue_pending`)
-  siguen y el siguiente arranca de inmediato. Para vaciar la cola entera hay que
-  llamar `POST /queue` con `{"clear": true}` (no lo hace esta funcion — solo corta
-  + lee).
+- `/interrupt` corta SOLO el prompt en ejecucion; sin `clear_pending` los pendientes
+  (`queue_pending`) siguen y el siguiente arranca de inmediato. Pasa
+  `clear_pending=True` para vaciar tambien la cola (POST /queue {"clear": true}).
 - No es idempotente en el sentido de "sin efecto": si hay algo ejecutandose, lo
-  mata. Si la cola esta vacia, el interrupt es inocuo (interrupted=True igual).
+  mata. Si la cola esta vacia, tanto el interrupt como el clear son inocuos
+  (`interrupted=True`/`cleared=True` igual, `queue_remaining=0`).
+- `queue_remaining` se lee al FINAL (GET /queue tras interrupt+clear): es
+  `queue_running + queue_pending`. Justo tras un interrupt sin clear puede ser >0
+  porque el siguiente pendiente ya arranco.
 - En fallo de red NO lanza: devuelve `ok=False` con el mensaje en `error`. Comprueba
-  `ok` antes de fiarte de los conteos.
+  `ok` antes de fiarte de `queue_remaining`.
 - Tras el interrupt conviene liberar VRAM con `POST /free` si vas a encolar otro
-  trabajo pesado (esta funcion no lo hace).
+  trabajo pesado (esta funcion no lo hace; ver el round-trip build -> submit -> wait).
+- Para operaciones de cola mas finas (borrar UN prompt por id, contar el historial)
+  usa `comfyui_queue_manage`; esta funcion se centra en el interrupt + clear masivo.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-28) — anade flag `clear_pending` (vacia la cola en la misma
+  llamada) + param `timeout`; el output pasa a {ok, interrupted, cleared,
+  queue_remaining, error} y se anaden tests (mock HTTP local).