ableton-mcp-ai/KIMI_K2_ACTIVE_HANDOFF.md

# Kimi K2 Active Handoff

Este es el handoff activo y actualizado.

Si otro documento contradice este, usa este archivo y despues valida con codigo y runtime.

## Estado real a 2026-03-30

### Arquitectura activa

- Cliente MCP -> `mcp_wrapper.py` -> `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
- Ableton Live -> `AbletonMCP_AI/__init__.py` -> `abletonmcp_init.py`
- `_Framework/` contiene el shim minimo para que el runtime no dependa de imports rotos

### Verificaciones hechas

- `server.py` tiene `89` tools y `89` nombres unicos
- los shims de `AbletonMCP_AI` cargan primero `abletonmcp_init.py`
- el repo publicado ya existe y tiene `README`, `ROADMAP`, `KNOWN_ISSUES` y `TODO`

### Lo que funciona

- MCP por `stdio`
- Control Surface `AbletonMCP_AI`
- `get_session_info` y `get_tracks` cuando Live esta abierto
- generacion de cancion con fallback de audio en Arrangement
- selecciones mas coherentes para reggaeton que antes

### Lo que sigue flojo

- `clear_all_tracks` limpia casi todo pero termina con error blando
- Z.ai devuelve `429` a veces
- falta same-pack estricto en algunos roles
- falta groove real derivado desde loops
- falta critica cerrada sobre audio renderizado
- falta automatizacion real robusta dentro del runtime

## Archivos que Kimi debe mirar primero

### Entrada MCP

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`

### Runtime de Live

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`

### Logica musical

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_manager.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\pack_brain.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\zai_judges.py`

## Tareas inmediatas explicadas para Kimi

### 1. Arreglar `clear_all_tracks`

Problema:

- al limpiar la sesion, el runtime devuelve `"Couldn't delete track."`
- aun asi deja casi todo limpio

Objetivo:

- limpiar sin error final
- dejar exactamente el estado esperado despues del reset

Archivos probables:

- `abletonmcp_init.py`
- `AbletonMCP_AI/abletonmcp_runtime.py`

Validacion:

- ejecutar limpieza dos veces seguidas sin crash
- `get_session_info` debe responder con cantidad consistente de tracks

### 2. Backoff, retry y cache para Z.ai

Problema:

- el selector usa jueces externos
- Z.ai puede responder `429`
- si no hay amortiguacion, la calidad del ranking cae

Objetivo:

- reintentos cortos con backoff
- cache local de decisiones por prompt/palette
- fallback heuristico limpio si la API falla

Archivo principal:

- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/zai_judges.py`

Validacion:

- si Z.ai falla, el sistema no debe romper generacion
- si el mismo prompt se repite, el cache debe evitar llamadas innecesarias

### 3. Same-pack estricto para `atmos_fx` y `vocal_shot`

Problema:

- esos roles todavia pueden salir bien aislados pero mal integrados al mismo universo sonoro

Objetivo:

- si existe opcion buena dentro del mismo pack musical principal, usarla primero
- solo salir del pack si no hay candidato valido

Archivos principales:

- `server.py`
- `sample_selector.py`
- `pack_brain.py`

Validacion:

- inspeccionar paths elegidos en una generacion de prueba
- confirmar que `atmos_fx` y `vocal_shot` vienen del mismo entorno del pack principal cuando sea posible

### 4. Groove extraction desde dembow loops

Problema:

- el ritmo actual es mejor que antes, pero todavia es demasiado reglado

Objetivo:

- leer transientes, densidad y acentos desde loops reales de dembow
- usar eso para posicionar kicks, claps y hats

Archivos probables:

- `audio_analyzer.py`
- `song_generator.py`
- `server.py`

Validacion:

- los patrones generados deben parecer menos mecanicos
- no deben volver al feel house straight

### 5. Smoke test de generacion async

Problema:

- hoy la generacion larga puede verse como timeout desde algunos clientes

Objetivo:

- un test corto que lance job async, haga poll y verifique estado final

Archivos probables:

- `server.py`
- script de prueba nuevo o reutilizable

Validacion:

- job creado
- job termina
- `get_generation_job_status` devuelve resultado util

## Reglas para no romper cosas

- no toques primero scripts legacy de root si el bug esta en el runtime o en `server.py`
- no tomes `KIMI_K2_CODEBASE_FIXES.md` como verdad total; tiene partes historicas
- no tomes `KIMI_K2_NOTE_API_FIX.md` salvo si el bug actual es escritura de notas MIDI
- no declares exito por un string bonito; valida con runtime
- no uses bash ni rutas `/c/...`

## Bucle de trabajo recomendado

1. leer `KIMI_K2_START_HERE.md`
2. leer `CLAUDE.md`
3. confirmar archivo activo
4. editar solo el archivo correcto
5. compilar
6. recargar Control Surface o reiniciar Live si hace falta
7. validar con `get_session_info`, `get_tracks` y log
8. documentar que cambio y que sigue faltando

## Si el puerto 9877 no responde

No declares bug del MCP automaticamente.

Primero verifica:

- Ableton abierto
- `AbletonMCP_AI` seleccionado en `Control Surface`
- log de Ableton sin crash
- `netstat -an | findstr 9877`

Si eso falla, el problema puede ser del runtime de Live, no del wrapper MCP.