Truncar el contexto de un fichero de arriba abajo deja a los agentes sin sus exports

La mayoría de generadores de contexto para agentes de código arrastran el mismo defecto: cuando un fichero no cabe en el presupuesto de tokens, lo recortan desde la línea 1 hacia abajo hasta agotar el cupo. Si el fichero tiene 1.200 líneas y el presupuesto da para 400, el modelo recibe las líneas 1 a 400 y del 401 al final no ve nada. TokenCap plantea cambiar el criterio de recorte: en lugar de cortar por arriba, repartir las muestras a lo largo de todo el fichero.

El problema no es estético. En código de producción, la estructura se reparte de forma muy predecible: arriba van los imports y las constantes, en medio está la lógica de negocio y las funciones auxiliares, y abajo quedan las interfaces exportadas, el registro de rutas, los module.exports y los enlaces de ciclo de vida. Si el agente nunca ve esas declaraciones finales, asume que no existen y genera código duplicado o directamente roto. El recorte secuencial convierte un fichero grande en un fichero distinto.

Qué hace el muestreo por tramos

El algoritmo vive en src/pack/evenSpan.js, dentro de TokenCap. La función computeEvenSpans recibe el número de líneas del fichero, el máximo de líneas que caben en el presupuesto y una lista de puntos de anclaje, y devuelve tramos equilibrados que garantizan que la cabecera con los imports, los bloques centrales y los exports del final estén representados de forma proporcional.

El detalle que lo separa de un simple muestreo aleatorio es que cada frontera del tramo cae en un límite de declaración estructural, no a mitad de una sentencia. El muestreo preserva además las firmas de función que encuentra en el AST, así que lo que llega al modelo sigue siendo código parseable y no un fragmento cortado por la mitad.

Con el mismo fichero de 1.200 líneas y un presupuesto de 400, el comportamiento típico capturaría las líneas 1 a 350 y descartaría el resto. El reparto por tramos entrega, por ejemplo, la cabecera con tipos y configuración en las líneas 1 a 80, la lógica central y los símbolos relevantes en las 220 a 310, y los manejadores de ciclo de vida junto a los exports del final en las 600 a 680, con 140 y 290 líneas plegadas entre medias. La herramienta permite revisar cómo se está presupuestando un fichero concreto con el comando tokencap make.

Por qué importa

Cualquier agente que edite un repositorio grande depende de ver la estructura completa del módulo antes de tocarlo, y el recorte por cabecera es la causa silenciosa de una buena parte de las ediciones duplicadas. La propuesta es sensata y el punto de partida está bien identificado, aunque todo el material que hay publicado se apoya en ejemplos de JavaScript: falta comprobar cómo se comporta el reparto cuando el AST es de otro lenguaje, donde los exports no se concentran de forma tan ordenada al final del fichero.