ableton-mcp-ai/docs/sprint_4_bloque_A.md

# SPRINT 4 — BLOQUE A: CARGA REAL, DIAGNÓSTICO Y ESTABILIZACIÓN (T001-T050)

> **Fecha**: 2026-04-11
> **Estado Sprint 3**: ✅ COMPLETO — 119 tools MCP, 64 handlers, 3 engines nuevos
> **Objetivo Sprint 4-A**: Que TODO lo que "dice" que hace, LO HAGA REALMENTE en Ableton
> **Revisión**: Qwen

---

## CONTEXTO

Sprint 3 entregó código que compila 100%. El problema: muchas acciones retornan
`"loaded": True` sin verificar que Ableton realmente las ejecutó. Este bloque se
enfoca en tres pilares:

1. **Verificación real** — cada handler confirma el estado POST-ejecución en Live
2. **Integración completa** — browser API ya implementada, ahora se usa en TODO el sistema
3. **Diagnóstico** — herramientas para que el usuario sepa exactamente qué funciona

---

## FASE A1: VERIFICACIÓN POST-EJECUCIÓN (T001-T010)

**T001** — `_cmd_load_sample_to_clip`: Agregar `_verify_clip_has_audio(slot)` que
inspecciona `slot.has_clip` y `clip.length > 0` DESPUÉS de la carga.
Retorna `verified: true/false` con `duration_beats` real si el clip existe.

**T002** — `_cmd_insert_device`: Agregar `_verify_device_on_track(track, device_name)`
que compara lista de devices ANTES y DESPUÉS. Retorna `verified: true` + `device_index`
real si el device apareció en `track.devices`.

**T003** — `_cmd_create_arrangement_midi_clip`: Verificar si `arrangement_clips` API
funcionó chequeando el clip existe en el track. Si Session fallback, marcar
`view: "session_fallback"` y retornar `clip_index` + URL del slot real.

**T004** — `_cmd_load_sample_to_drum_rack_pad`: Verificar que el pad tiene cadena
después del intento. Acceder a `pad.chains[0].devices[0].sample.file_path`
y comparar con el fname buscado. Retornar `verified_path`.

**T005** — `_cmd_generate_dembow_clip`: Verificar que las notas se escribieron
exactamente. Leer el clip con `clip.get_notes()` y comparar count.
Retornar `notes_written: N, notes_verified: M`.

**T006** — `_cmd_generate_midi_clip`: Agregar verificación de notas post-escritura.
Si `clip.get_notes()` retorna vacío cuando se enviaron notas, loguear el error
y reintentar con `replace_selected_notes` si disponible.

**T007** — `_cmd_create_drum_kit`: Después de crear el Drum Rack, verificar que
`track.devices` contiene el device. Acceder a `device.drum_pads` y contar pads
activos. Retornar `pads_active`, `drum_rack_index`.

**T008** — `_cmd_configure_eq`: Verificar que el EQ Eight está en la cadena.
Leer `device.parameters` y confirmar que se aplicaron los valores.
Retornar `parameters_verified: {band: value}`.

**T009** — `_cmd_setup_sidechain`: Verificar que el Compressor tiene `sidechain_active`.
Acceder a `device.sidechain` si existe. Retornar `sidechain_confirmed: true/false`.

**T010** — Crear handler `_cmd_verify_track_setup(track_index)`:
- Lista todos los devices del track
- Lista clips activos en Session View
- Informa volumen, pan actual
- Retorna snapshot completo del track para debugging

---

## FASE A2: BROWSER API — USAR EN TODO EL SISTEMA (T011-T020)

**T011** — `_cmd_load_samples_for_genre` (T008): Actualmente usa solo
`sample_selector.select_for_genre()` para paths. Integrar `_browser_load_audio()`
para cada sample, con fallback a `create_audio_clip`. Retornar qué método funcionó
por cada sample.

**T012** — `_cmd_create_drum_kit` (T009): Actualmente crea Drum Rack via
`create_midi_track()` pero no carga el Drum Rack device. Integrar
`_browser_load_device(t, "Drum Rack", "instruments")` antes de cargar samples.
Verificar que el Drum Rack apareció antes de intentar cargar pads.

**T013** — `_cmd_build_track_from_samples` (T010): Usar `_browser_load_audio()`
en lugar de confiar en `create_audio_clip`. Agregar lógica de fallback:
si browser falla, crear MIDI track con nota de instrucción.

**T014** — `_cmd_insert_device` → extender lookup: Actualmente busca solo en una
sección. Agregar búsqueda secundaria en TODAS las secciones si la primera falla.
Orden: `instruments → audio_effects → midi_effects → packs`.

**T015** — Nuevo handler `_cmd_scan_browser_section(section_name, depth=2)`:
- Escanea una sección del browser Live y retorna árbol de items
- Sections: "instruments", "audio_effects", "sounds", "user_folders", "packs"
- Útil para debug: saber exactamente qué ve el sistema en el browser
- Retorna lista de items con `name`, `is_loadable`, `is_folder`

**T016** — Nuevo tool MCP `scan_browser_section(section, depth)` en `server.py`:
- Llama a `_cmd_scan_browser_section`
- Permite al usuario descubrir qué devices/samples tiene disponibles
- Retorna JSON con árbol navegable

**T017** — `_cmd_configure_eq`: Si el device no existe en el track, PRIMERO
insertar EQ Eight via `_browser_load_device`, LUEGO configurar parámetros.
Secuencia: insert → verify → configure.

**T018** — `_cmd_configure_compressor`: Si no hay Compressor, insertar via
browser antes de configurar. Verificar la inserción. Mismo patrón que T017.

**T019** — `_cmd_setup_sidechain`: Insertar Compressor si no existe,
configurar la fuente de sidechain. Usar `device.sidechain_enabled = True` si disponible.
Retornar los parámetros realmente configurados.

**T020** — Nuevo handler `_cmd_add_libreria_to_browser()`:
- Lee path de `libreria/reggaeton` desde constante
- Intenta agregar el folder a Live's user library via `application().browser`
- Retorna `added: true/false` con instrucción manual si falla

---

## FASE A3: ARRANGEMENT VIEW — IMPLEMENTACIÓN COMPLETA (T021-T030)

**T021** — `_cmd_create_arrangement_midi_clip`: Agregar soporte para `song.record_mode`.
Si `song.record_mode` está disponible, configurar overdub antes de fire.
Retornar `arrangement_mode_set: true/false`.

**T022** — Nuevo handler `_cmd_set_arrangement_position(bar)`:
- `song.current_song_time = bar * beats_per_bar`
- `app.view.show_view("Arranger")`
- Retorna posición actual del playhead

**T023** — Nuevo handler `_cmd_fire_clip_to_arrangement(track_index, clip_index, target_bar)`:
- Pos playhead en `target_bar`
- Activa `song.arrangement_overdub = True`
- Dispara el clip: `track.clip_slots[clip_index].fire()`
- Espera `clip.length` beats en la queue de `_pending_tasks`
- Desactiva overdub: `song.arrangement_overdub = False`
- Retorna `recorded_to_bar: target_bar`

**T024** — `_cmd_duplicate_session_to_arrangement` (T014): Reescribir usando
`_cmd_fire_clip_to_arrangement` para cada clip+escena. Calcular posición en bars
basada en `scene_index * section_length`. Retorna clips colocados + posición.

**T025** — Nuevo handler `_cmd_get_arrangement_clips(track_index)`:
- Lee todos los clips de arrangement via `track.arrangement_clips` si disponible
- Retorna lista con `name`, `start_time`, `length`, `has_notes`
- Si no disponible, retorna vacío con `method: "not_available"`

**T026** — Nuevo handler `_cmd_show_arrangement_view()`:
- `app.view.show_view("Arranger")`
- `app.view.show_view("Detail/Clip")` para mostrar detalle
- Retorna `view: "arranger"`

**T027** — Nuevo handler `_cmd_show_session_view()`:
- `app.view.show_view("Session")`
- Retorna `view: "session"`

**T028** — `_cmd_build_arrangement_structure`: Usa `_cmd_fire_clip_to_arrangement`
para colocar clips reales en posiciones de la estructura (Intro, Verse, Drop, etc.)
en lugar de solo crear escenas en session view.

**T029** — Nuevo handler `_cmd_loop_arrangement_region(start_bar, end_bar)`:
- `song.loop_start = start_bar * beats_per_bar`
- `song.loop_length = (end_bar - start_bar) * beats_per_bar`
- `song.loop_on = True`
- Retorna `loop_set: true`

**T030** — Nuevo handler `_cmd_capture_to_arrangement()`:
- Equivalente a "Capture" de Live: `app.get_document().capture_midi()` si disponible
- Fallback: instrucción de cómo usar Capture manualmente
- Retorna `captured: true/false`

---

## FASE A4: DIAGNÓSTICO Y MONITOREO (T031-T040)

**T031** — Nuevo handler `_cmd_get_live_version()`:
- `Live.Application.get_application().get_major_version()`
- `Live.Application.get_application().get_minor_version()`
- Retorna `version: "12.x.x"`, `build: N`

**T032** — Nuevo handler `_cmd_get_track_details(track_index)`:
- Snapshot completo de un track: devices, clips, volumes, routing
- Para debugging: `has_input`, `has_output`, `arm`, `mute`, `solo`
- Lista cada device con parámetros accesibles

**T033** — Nuevo handler `_cmd_get_device_parameters(track_index, device_index)`:
- Lista todos los parámetros de un device
- `device.parameters` → `{name, value, min, max, is_quantized}`
- Útil para saber cómo configurar el device vía API

**T034** — Nuevo handler `_cmd_set_device_parameter(track_index, device_index, param_name, value)`:
- Busca parámetro por nombre en `device.parameters`
- Setea `param.value = value`
- Verifica que el cambio se aplicó
- Retorna `parameter`, `old_value`, `new_value`

**T035** — Nuevo handler `_cmd_get_clip_notes(track_index, clip_index)`:
- Lee las notas de un MIDI clip via `clip.get_notes()`
- Retorna lista de `{pitch, start, duration, velocity, mute}`
- Con estadísticas: `note_count`, `min_pitch`, `max_pitch`, `duration_bars`

**T036** — Nuevo handler `_cmd_test_browser_connection()`:
- Verifica que `application().browser` es accesible
- Lista las secciones disponibles: sounds, instruments, audio_effects, etc.
- Retorna `browser_ok: true/false`, `sections: [...]`

**T037** — Nuevo handler `_cmd_test_sample_loading(sample_path)`:
- Tests: `os.path.isfile()` → path OK
- Tests: `_browser_load_audio()` → browser OK
- Tests: `create_audio_clip()` si disponible
- Retorna `path_ok`, `browser_ok`, `direct_ok`, `recommended_method`

**T038** — Nuevo handler `_cmd_get_session_state()`:
- `song.current_song_time` → posición actual
- `song.is_playing`, `song.tempo`, `song.signature_numerator`
- Lista clips activos por track
- Retorna snapshot completo del estado de Session

**T039** — Nuevo tool MCP `get_system_diagnostics()` en `server.py`:
- Combina: get_live_version + test_browser_connection + get_session_state
- Retorna JSON con estado completo del sistema
- Primer tool que ejecutar para diagnosticar problemas

**T040** — Nuevo tool MCP `test_real_loading(sample_path)` en `server.py`:
- Llama a `_cmd_test_sample_loading`
- Retorna qué métodos de carga funcionan en el Live actual
- Guía al usuario sobre qué esperar

---

## FASE A5: ROBUSTEZ Y ESTABILIDAD (T041-T050)

**T041** — Agregar timeout global a `_cmd_*` handlers: Si un handler tarda
más de 3s (detectado via `time.time()`), retornar `timeout: true` y limpiar
`_pending_tasks` parcialmente. Previene bloqueos de Ableton.

**T042** — `_dispatch()`: Agregar manejo de `JSONDecodeError` y `KeyError`
explícitos. Retornar error descriptivo con el comando que falló.
Loguear en Ableton con `self.log_message`.

**T043** — Proteger `update_display()`: Atrapar excepciones dentro del loop
de `_pending_tasks`. Si una task lanza excepción, remover y continuar con la
siguiente. Nunca dejar que una task rota bloquee el drain.

**T044** — `_tcp_server_thread`: Si la conexión se cierra abruptamente,
cerrar el socket limpiamente. Agregar `socket.SO_REUSEADDR` si no está presente.
Reiniciar listener automáticamente tras error de conexión.

**T045** — Agregar límite a `_pending_tasks`: Si la queue supera 100 items,
droppear las tareas más viejas y loguear warning. Previene acumulación sin límite
cuando Ableton está bajo carga y `update_display()` no puede drenar rápido.

**T046** — `_cmd_get_tracks()`: Si un track da error al leer un atributo
(e.g., track sin nombre), continuar con el siguiente en lugar de fallar todo.
Agregar `try/except` granular por atributo.

**T047** — `_cmd_generate_full_song()`: Si un sub-handler falla durante
el pipeline, continuar con los siguientes tracks. Retornar lista de errores
al final pero no abortar. Comportamiento "best effort" para producción completa.

**T048** — Todos los handlers que crean tracks: Verificar que el índice
solicitado no excede `len(song.tracks)`. Si se intenta acceder a track[N]
y N>=len, retornar error claro en lugar de IndexError sin contexto.

**T049** — `_browser_search`: Agregar límite de tiempo: si la recursión
supera 5 segundos (verificar con `time.time()`), abortar y retornar `None`
en lugar de bloquear el thread de Ableton indefinidamente.

**T050** — Crear `_cmd_health_check()`:
- Ejecuta 5 checks: TCP OK, song accesible, tracks accesibles, browser accesible, update_display activo
- Retorna score 0-5 y descripción de cada check
- Tool MCP `health_check()` que llama a este handler
- Primero que ejecutar tras abrir Ableton

---

## ARCHIVOS A MODIFICAR (Bloque A)

| Archivo | Cambios |
|---------|---------|
| `__init__.py` | +25 handlers nuevos, robustez en handlers existentes |
| `mcp_server/server.py` | +10 tools MCP: scan_browser, health_check, get_system_diagnostics, test_real_loading, etc. |

## RESTRICCIONES
1. Compilar tras cada archivo: `python -m py_compile "<path>"`
2. `libreria/` → solo lectura
3. NO modificar engines del Sprint 1/2/3
4. Handlers de verificación son SOLO-LECTURA: no mutan estado
5. Retornar siempre JSON con `status` + `result` o `error`