Gestión del historial

El entorno de ejecución mantiene el historial de conversación de cada sesión de agente y envía al modelo un historial de trabajo orientado al proveedor. Dos límites complementarios operan sobre representaciones distintas:

1. El recorte según el presupuesto de tokens actúa sobre el historial de trabajo de ChatMessage destinado al proveedor y descarta los turnos completos más antiguos hasta que el contexto estimado se ajuste al presupuesto de tokens.
2. Recorte estructurado del número de mensajes modifica Agent::history (ConversationMessage), utilizado por los turnos de Agent de RPC, gateway y ACP, cuando supera el límite efectivo de mensajes del agente estructurado. Los bucles de canal del daemon que llaman a la ruta heredada agent::run utilizan el límite independiente de mensajes sin procesar que se describe a continuación.

El recorte por presupuesto de tokens y el límite estructurado de recuento de mensajes conservan los turnos de forma atómica. Un turno comienza en un mensaje real del usuario e incluye la respuesta del asistente y todas las llamadas a herramientas y sus resultados antes del siguiente mensaje del usuario. Por tanto, el recorte no separa una llamada a herramienta de su resultado.

Retención de turno completo

history_trim::trim_to_recent_turns aplica el presupuesto de tokens, mientras que history_trim::trim_conversation_to_recent_turns aplica el límite estructurado de recuento de mensajes. Cada uno conserva el turno completo más reciente incluso cuando ese turno por sí solo supera el límite correspondiente. Esto es intencional: preservar un turno actual completo es más seguro que satisfacer un límite numérico descartando sus mensajes más recientes o interrumpiendo un intercambio de herramientas.

Se conservan los mensajes del sistema iniciales. Cuando no se necesita ningún recorte, el orden y la estructura de los mensajes se mantienen sin cambios.

Presupuesto de tokens

El presupuesto de tokens proviene de ResolvedRuntime::effective_context_budget():

• Cuando history_pruning.enabled está configurado con un valor positivo de history_pruning.max_tokens, el presupuesto es el menor entre ese valor y max_context_tokens.
• De lo contrario, el presupuesto es max_context_tokens.

Los conteos de tokens son estimados por history::estimate_history_tokens: aproximadamente cuatro caracteres por token más cuatro tokens de encuadre por mensaje. Esto es una heurística, no un tokenizador de proveedor.

El recorte del presupuesto de tokens se ejecuta antes de la primera llamada al proveedor en un turno cuando el historial ya supera el presupuesto efectivo, y en los límites de llamadas al proveedor entre iteraciones del bucle de herramientas, incluso de forma reactiva cuando un proveedor informa que se superó la ventana de contexto. Conserva turnos completos, por lo que nunca divide un intercambio de herramientas.

Límite de recuento de mensajes estructurado

max_history_messages es el valor configurado en el perfil de ejecución del agente. Un valor configurado explícitamente es autoritativo tanto para la ruta sin procesar heredada como para el historial estructurado del agente, incluido 0. Dado que el recorte estructurado siempre retiene el turno completo más reciente, un valor de 0 elimina los turnos anteriores pero no borra el turno actual.

Cuando se omite max_history_messages, el límite bruto heredado permanece en 50. El límite efectivo del agente estructurado se deriva de la tolerancia del bucle de herramientas:

max(50, 2 * max_tool_iterations + 2)

Cada iteración de herramienta puede añadir una llamada a herramienta y un resultado de herramienta; los dos espacios adicionales cubren el mensaje del usuario y la respuesta final del asistente. Con el valor predeterminado max_tool_iterations = 10, el límite derivado se mantiene en 50.

Recorte visible

Cada vez que el recorte del presupuesto de tokens o el límite estructurado de recuento de mensajes descarta turnos más antiguos, el runtime:

1. Inserta una nota de contexto antes del primer turno conservado para que el modelo sepa que se omitió contexto anterior.
2. Emite HistoryTrimmed con el número de mensajes descartados, turnos retenidos y un motivo que identifica el presupuesto de tokens o el límite de mensajes.

El evento se expone a través del transporte del cliente activo y a través de la ruta del observador utilizada por los paneles de control y los suscriptores de eventos. El recorte, por lo tanto, no es exclusivo del registro y no es silencioso ni para el modelo ni para los clientes conectados.

La ruta heredada agent::run en loop_.rs es una excepción sin modificar. Su límite de ChatMessage sin procesar en history::trim_history sigue siendo a nivel de mensaje y notifica el recorte únicamente a través de los registros, sin la traza de navegación ni el evento HistoryTrimmed. Esta ruta sirve para el uso interactivo, así como para las llamadas de una sola vez y de daemon no interactivo, cron, subagente y SOP.

Seguridad de emparejamiento

La retención de turno completo es la garantía principal de emparejamiento de herramientas: una llamada a herramienta y su resultado pertenecen al mismo turno y se retienen o descartan juntos. El barrido de huérfanos sigue siendo una red de seguridad final para historiales que ya eran inconsistentes, como sesiones restauradas o modificadas externamente.

Los límites de longitud de los resultados de herramientas son independientes. max_tool_result_chars acota un resultado individual cuando se registra; no recorta el historial de la conversación. La aplicación del contexto del lado del proveedor también es independiente, aunque un desbordamiento del proveedor puede desencadenar el recorte reactivo del presupuesto de tokens del entorno de ejecución.