chorned/heb-mcp.skill

heb-mcp.skill (TikTok-2-HEB) — Habilidad para Agente

Gestiona carritos de compras H-E-B en vivo, resuelve productos preferidos del hogar basados en el historial de compras, recorta cupones y transforma URLs de videos de cocina en carritos H-E-B escalados, auditados por despensa, con sustituciones deterministas por falta de stock.

---

🎯 Condiciones de Activación

Activa esta habilidad siempre que:

1. Un usuario pida buscar en H-E-B, revisar su carrito, cambiar su tienda preferida o método de entrega (Recogida en Tienda vs. Entrega a Domicilio), recortar cupones, o añadir/eliminar comestibles en H-E-B (ej. "Añade leche entera y tortillas de mantequilla a mi carrito H-E-B").
2. Un usuario autorizado comparta una URL de cocina o receta de TikTok (tiktok.com, vm.tiktok.com), Instagram Reels (instagram.com/reel/), o YouTube Shorts (youtube.com/shorts/).
3. Un usuario pida convertir, escalar o pedir los ingredientes de un video de receta (ej. "Pide los ingredientes de esta receta en H-E-B", "Pon esta cena de TikTok en mi carrito").
4. Un usuario responda a un hilo de revisión de compras existente con ajustes posteriores al montaje (ej. "añadir salsa de soja", "cambiar salmón normal por salmón rojo salvaje", "hacer ese cambio permanente").
5. Un usuario pida configurar o poner en marcha heb-mcp.skill (TikTok-2-HEB) por primera vez.

---

🚀 Configuración Inicial (Incorporación Guiada por el Agente)

Cuando un usuario te pida configurar este proyecto, maneja los pasos técnicos por él y solo haz preguntas breves en lenguaje natural:

1. Instala el entorno y los binarios:

   uv venv --python 3.11 .venv && source .venv/bin/activate && uv pip install -r requirements.txt
   playwright install chromium
   cp -n .env.example .env
   cp -n config/household.example.yaml config/household.yaml
   cp -n config/pantry_staples.example.json config/pantry_staples.json
   

2. Haz al usuario preguntas rápidas de configuración:
   • Tienda H-E-B preferida y método de entrega: Pregunta en qué tienda H-E-B compra (actualiza HEB_STORE_ID en .env y store en config/household.yaml, y ayúdale a cambiar su tienda activa o alternar entre Recogida en Tienda y Entrega a Domicilio cuando lo solicite).
   • Tamaño del hogar: Pregunta cuántos adultos/niños cocina (actualiza config/household.yaml).
3. Cosecha la sesión y sincroniza pedidos anteriores: Pide al usuario que se asegure de haber iniciado sesión en heb.com en Safari o Chrome, luego ejecuta:

   python scripts/heb_client.py --harvest
   python scripts/cache_manager.py update-preferred-skus
   python tests/test_skill_setup.py
   

4. Configura la tarea programada diaria de renovación automática de tokens: Recomienda encarecidamente al usuario que te permita instalar una tarea recurrente cada 24 horas (0 9 * * * cd <RUTA_DEL_REPO> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1) para que su sesión de H-E-B se mantenga activa automáticamente.

---

🔒 Invariantes Operacionales y Barreras de Seguridad

1. Barrera Humana en el Ciclo para el Pago:
   • El agente monta artículos en el carrito y recorta cupones digitales.
   • El agente NUNCA DEBE enviar el pago, reservar ventanas de entrega/recogida ni finalizar el pedido.
   • La revisión final y la ejecución del pago siempre quedan en manos del usuario dentro de la aplicación oficial My H-E-B.
2. Extracción sin Autenticación:
   • Invoca siempre scripts/extract_recipe_media.py sin requerir inicios de sesión personales en TikTok/Instagram ni cookies de sesión.
3. Invariante Anti-Envenenamiento de Caché:
   • Las sustituciones por falta de stock (Nivel 2/3/4) deben permanecer estrictamente efímeras para ese pedido específico.
   • NUNCA sobrescribas primary_sku en cache/recipes/<slug>.yaml a menos que el usuario ordene explícitamente: "hacer ese cambio permanente" o "usar siempre esta marca".
4. División de Preparación Aptas para Niños:
   • Cuando kid_friendly_split esté habilitado, separa la capsaicina/picante (sriracha, hojuelas de chile, cayena, jalapeños) de la base de la sartén. Mantén el plato principal suave, sirve la porción del niño primero y sazona las porciones de adultos al final.
   • Añade recordatorios para cortar las proteínas y los alimentos que puedan causar atragantamiento en cubos de 1/2 pulgada.
5. Renovación Automática de Tokens (Recomendación de Tarea Programada Diaria):
   • Aunque el token de acceso de sesión corta (sat) de H-E-B rota cada 30 minutos, heb_graphql.py lo renueva automáticamente bajo demanda usando el token de sesión larga (sst).
   • Durante la configuración inicial o después de cosechar/renovar una sesión, recomienda proactivamente al usuario que te permita configurar una tarea programada cada 24 horas que mantenga su sesión subyacente de H-E-B y el token antibot (reese84) validados en segundo plano, para que no tenga que volver a iniciar sesión manualmente antes de ir de compras.

---

🛠️ Flujo de Trabajo de Ejecución Paso a Paso

Paso 1: Consulta de Caché Pre-Vuelo

Antes de realizar la extracción de medios o llamadas a la API, verifica si el video ya ha sido analizado y almacenado en caché:

python scripts/cache_manager.py lookup --query "<URL_O_ID_DEL_VIDEO>"

• ACIERTO: Carga el YAML de la receta en caché. Continúa directamente al Paso 4 (Montaje del Carrito) usando las definiciones de primary_sku en caché.
• FALLO: Continúa al Paso 2 (Extracción de Medios).

Paso 2: Extracción Multimodal sin Autenticación

Ejecuta el pipeline de extracción de 3 pasos:

python scripts/extract_recipe_media.py "<URL_DEL_VIDEO>"

1. Paso 1: Captura el título del video, descripción, usuario que subió y subtítulos automáticos.
2. Paso 2: Limpia las marcas de los subtítulos, elimina marcas de tiempo y desduplica las repeticiones de los títulos continuos.
3. Paso 3: Si la transcripción es escasa (< 3 tokens de medidas culinarias), extrae automáticamente el flujo de audio o fotogramas clave.

Paso 3: Análisis de Receta, Escalado del Hogar y Auditoría de Despensa

1. Escalado del Hogar: Escala las cantidades de los ingredientes desde el rendimiento original (ej. 4 porciones) hasta las porciones objetivo (por defecto 2.5 para 2 adultos + 1 niño) usando HouseholdScaler.
2. Desduplicación de Despensa: Verifica los ingredientes contra config/pantry_staples.json usando PantryComparator. Mueve los artículos coincidentes (sal, pimienta, aceite de cocina, salsa de soja, ajo en polvo) a pantry_staples_skipped.
3. Recordatorios de Preparación para Niños: Genera adaptaciones aptas para niños si se detectan ingredientes picantes o proteínas enteras.

Paso 4: Coincidencia con el Catálogo H-E-B y Cascada de 5 Niveles

Para cada ingrediente en ingredients_to_buy (o solicitudes ad-hoc del usuario), busca coincidencias en el catálogo de la tienda H-E-B local usando scripts/heb_client.py:

• Nivel 0 (Resolución de SKU Preferido y Escalado de Tamaño de Paquete): Coincide contra cache/preferred_skus.json (claves canónicas y arreglos de alias) poblado a partir de pedidos anteriores y fijaciones manuales. Calcula automáticamente cantidades enteras de paquetes (ej. 48 oz de volumen de receta / 32 oz por paquete -> 2 paquetes). Si está en stock, se monta directamente como Nivel 0. Si está agotado, se desciende suavemente al Nivel 1.
• Nivel 1 (Coincidencia Exacta de SKU): Añade el SKU primario de la receta existente si está en stock.
• Nivel 2 (Jerarquía de Marcas): Si el SKU primario está agotado (OOS), sustituye usando brand_hierarchy (H-E-B → H-E-B Organics → Central Market → Mi Tienda → Hill Country Fare → National Brand).
• Nivel 3 (Intercambio Orgánico ↔ Convencional): Intercambia orgánico por convencional (o viceversa) si la tienda solo tiene uno en stock.
• Nivel 4 (Ajuste de Tamaño de Paquete / Escalado Humano): Ajusta cantidades o marca la categoría como sin stock con ⚠️ OUT OF STOCK (NEEDS HUMAN CALL).

Paso 5: Montaje Directo del Carrito mediante GraphQL y Recorte de Cupones (Sin Clics Lentos en la UI)

Monta los artículos y recorta cupones directamente mediante operaciones GraphQL autenticadas (consultas persistentes cartEstimated, cartItemV2, CouponClip provenientes de texas-grocery-mcp) usando tokens de sesión de Chrome CDP cosechados (127.0.0.1:9222) / rookiepy:

# 1. Cosecha o renueva los tokens de sesión en vivo
python scripts/heb_client.py --harvest

# 2. Sincroniza los SKU preferidos de pedidos anteriores y "Cómpra de nuevo"
python scripts/cache_manager.py update-preferred-skus

# 3. Fija manualmente un producto favorito como SKU preferido (protegido de la sincronización automática)
python scripts/cache_manager.py pin-preferred-sku \
  --ingredient "leche entera" \
  --sku "4122012345" \
  --product "123456" \
  --name "H-E-B Organics Leche Entera" \
  --package-size "1 gal"

# 4. Resuelve un ingrediente ad-hoc o prueba el tamaño de paquete
python scripts/heb_client.py --resolve-sku "48 oz caldo de res"

# 5. Monta los artículos candidatos (requiere --confirm para humano en el ciclo)
python scripts/heb_client.py --stage-sku "48 oz caldo de res" --confirm
# o directamente por ID de producto:
python scripts/heb_client.py --cart-add <ID_PRODUCTO> [--sku <ID_SKU>] [--qty <N>] --confirm

# 6. Inspecciona el carrito actual en vivo
python scripts/heb_client.py --cart-get

# 7. Elimina un artículo del carrito si se intercambió
python scripts/heb_client.py --cart-remove <ID_PRODUCTO> [--sku <ID_SKU>] --confirm

# 8. Recorta cupones digitales
python scripts/heb_client.py --coupon-clip <ID_CUPON> --confirm

[!IMPORTANT] Barrera Humana en el Ciclo para el Pago: El AGENTE tiene prohibido ejecutar mutaciones de pago, reserva de ventanas de entrega/recogida. Solo montaje de carrito y recorte de cupones; Carl siempre revisa y pulsa el pago final en la app móvil My H-E-B.

⏱️ Tarea Programada Recomendada (Renovación Diaria de Sesión)

Aunque el token de corta duración sat de H-E-B rota cada 30 minutos y se renueva automáticamente bajo demanda mediante sst, recomienda al usuario que tenga una tarea programada diaria (macOS/Linux con cron o schtasks en Windows) que renueve y valide la sesión una vez cada 24 horas. Ofrece instalarla en su crontab:

0 9 * * * cd /ruta/a/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1

(O usa scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh si se desean notificaciones por Slack.)

Paso 6: Persistencia de la Receta en Caché

Persiste la receta analizada para asegurar que futuras ejecuciones sigan la Ruta Rápida:

python scripts/cache_manager.py save --file <ARCHIVO_RECETA_YAML>

Paso 7: Resumen de Revisión para Móvil (iMessage / Slack)

Formatea la revisión para una lectura limpia en pantallas móviles (evita tablas Markdown, usa viñetas con emojis limpias):

🛒 Carrito H-E-B Montado: Bocaditos Crujientes de Salmón con Miel y Ajo
Escalado para 2 Adultos + 1 Niño (~2.5 porciones)

👶 Nota de Preparación para Niños:
• Reserva la 1 cda de sriracha fuera del glaseado de la sartén principal. Sirve la porción del niño primero, luego mezcla las porciones de adultos con la sriracha.
• Corta el salmón del niño en cubos de 1/2 pulgada.

✅ Añadido al Carrito H-E-B (4 artículos):
• 1x Filete de Salmón del Atlántico Fresco H-E-B (~1.25 lb) — $13.74
• 1x Miel de Trébol Pura H-E-B (12 oz) — $4.48
• 1x Cebollas Verdes Frescas (1 manojo) — $0.88
• 1x Arroz Jasmine H-E-B (32 oz) — $2.74

🔄 Sustituido Automáticamente (Sin Stock en Tienda):
• 2x Floretes de Brócoli H-E-B (bolsa de 10 oz) — $4.56
  (Coronas Orgánicas de 1 lb agotadas; sustituido por 2 bolsas de 10 oz solo para este pedido)

🎟️ Cupones Recortados:
• $1.00 de descuento en Bandeja de Mariscos Frescos H-E-B

🏠 Verificación de Despensa (Omitido — responde para añadir):
• Salsa de soja (3 cdas), Ajo (4 dientes), Maicena (2 cdas), Aceite de sésamo (1 cdita)

📱 Siguiente Paso:
Responde si quieres añadir un artículo de despensa (ej. "añadir salsa de soja") o cambiar una marca. ¡Si no, abre la app My H-E-B para revisar y pulsar el pago!

---

🔄 Comandos de Respuesta Posteriores al Montaje

Cuando el usuario responda al hilo de revisión montado:

1. "Añadir [artículo de despensa]" (ej. "se nos acabó la salsa de soja, añádela"):
   • Resuelve a través del motor de SKU preferido de Nivel 0 y móntalo en el carrito: python scripts/heb_client.py --stage-sku "salsa de soja" --confirm
   • Confirma con una respuesta breve: "Se ha añadido 1x Salsa de Soja Reducida en Sodio H-E-B a tu carrito."
2. "Cambia [artículo] por [preferencia]" (ej. "cambia salmón normal por salmón rojo salvaje"):
   • Elimina el SKU antiguo del carrito y añade el SKU preferido.
   • Pregunta: "Se ha cambiado por salmón rojo salvaje para este pedido. ¿Te gustaría que hiciera este cambio permanente para futuros pedidos de esta receta?"
3. "Haz ese cambio permanente":
   • Ejecuta python scripts/cache_manager.py promote-sku ... para actualizar primary_sku en cache/recipes/<slug>.yaml y fíjalo en cache/preferred_skus.json con source: "manual_override".
   • Confirma: "Caché de receta actualizada: Central Market Wild Sockeye es ahora tu SKU primario para esta receta y ha sido fijado como tu SKU preferido."
4. "Cambiar tienda preferida a [Tienda]" / "Cambiar a Recogida en Tienda o Entrega a Domicilio":
   • Actualiza HEB_STORE_ID en .env y store en config/household.yaml, o actualiza el modo de tienda/entrega activo en la sesión H-E-B, y vuelve a verificar la disponibilidad de los artículos del carrito en la nueva tienda.