Recuperacao de Contexto

O ChatCLI implementa um sistema de recuperacao automatica de contexto que lida com dois tipos de falha comuns em sessoes longas: overflow da janela de contexto (“prompt too long”) e limite de tokens de saida. Quando a API rejeita uma requisicao por excesso de tamanho, o sistema aplica estrategias progressivamente mais agressivas para recuperar a sessao sem perder a conversa.

Recuperacao de Context Overflow

Quando a API retorna um erro de “context too long”, o ChatCLI aplica ate 3 niveis de recuperacao antes de desistir:

Nivel 1: Orcamento Agressivo
Nivel 2: Truncamento de Emergencia
Nivel 3: Truncamento Nuclear

Primeira tentativa: reduz os limites de orcamento pela metade e limpa desalinhamentos.Acoes:

Repara pareamento de tool results (remove orfaos, injeta sinteticos)
Reduz DefaultTurnBudgetChars e DefaultPerResultMaxChars para 50% dos valores originais
Aplica enforcement de orcamento com limites reduzidos
Trunca mensagens longas do assistente para 5.000 chars

Os limites originais sao restaurados apos a aplicacao. Apenas o historico atual e afetado pela reducao.

Segunda tentativa: mantem apenas mensagens do sistema e as ultimas N mensagens.Acoes:

Preserva todas as mensagens de sistema (system prompt, bootstrap, contextos)
Mantem as ultimas 10 mensagens nao-sistema (configuravel)
Garante que o historico comeca com uma mensagem user (requisito da API)
Valida pareamento de tool results no historico truncado

Terceira tentativa: mantem apenas o minimo para continuar.Acoes:

Preserva mensagens de sistema
Mantem apenas as ultimas 4 mensagens (2 trocas user/assistant)
Injeta mensagem de aviso explicando que o contexto foi compactado

[Context was automatically compacted due to size limits.
Previous conversation history has been summarized.
Continue from where you left off.]

Deteccao de Erro

O sistema reconhece multiplas formas de erro de overflow:

Mensagem de Erro	Provedor
`context length exceeded`	Anthropic
`prompt is too long`	OpenAI
`request too large`	Varios
`max_tokens exceed`	Varios
`input too long`	Google
`token limit`	Generico

Escalacao de Max Output Tokens

Quando o modelo para de gerar por atingir o limite de max_tokens, o ChatCLI pode escalar automaticamente:

Tentativa	Acao
1a	Dobra o `max_tokens` atual (ate o cap do provedor)
2a	Dobra novamente (ate o cap do provedor)
3a+	Para de escalar, retorna conteudo parcial

Mensagem de Continuacao

Quando o modelo e interrompido por limite de tokens, o ChatCLI injeta uma mensagem de continuacao:

Your response was cut off at the token limit.
Resume DIRECTLY from where you stopped — do not repeat any content.
Continue the implementation or explanation from the exact point of interruption.

A mensagem instrui o modelo a continuar de onde parou, evitando repeticao de conteudo ja gerado.

Configuracao

Variavel de Ambiente	Descricao	Default
`CHATCLI_MAX_RECOVERY_ATTEMPTS`	Tentativas maximas de recuperacao de contexto	3
`CHATCLI_MAX_TOKEN_ESCALATIONS`	Escalacoes maximas de max_tokens	2
`CHATCLI_EMERGENCY_KEEP_MESSAGES`	Mensagens mantidas no truncamento de emergencia	10

Ratio de Orcamento Agressivo

No nivel 1, os limites de orcamento de tool results sao multiplicados por 0.5 (50%). Isso significa:

Parametro	Normal	Nivel 1 Recuperacao
Budget por turno	200.000 chars	100.000 chars
Max por resultado	20.000 chars	10.000 chars

Fluxo de Recuperacao

API retorna erro "context too long"
  │
  ├─ Tentativa 1: Orcamento agressivo (50%) + pairing cleanup
  │   └─ Reenvia para API
  │       ├─ Sucesso → continua normalmente
  │       └─ Falha → proxima tentativa
  │
  ├─ Tentativa 2: Emergency truncate (system + ultimas 10 msgs)
  │   └─ Reenvia para API
  │       ├─ Sucesso → continua com historico reduzido
  │       └─ Falha → proxima tentativa
  │
  └─ Tentativa 3: Nuclear truncate (system + ultimas 4 msgs)
      └─ Reenvia para API
          ├─ Sucesso → continua com historico minimo
          └─ Falha → erro reportado ao usuario

Apos o truncamento nuclear (nivel 3), o modelo perde todo o contexto da conversa anterior. Apenas as ultimas 2 trocas sao mantidas. Use /compact proativamente para evitar chegar a esse ponto.

Interacao com Outros Sistemas

A recuperacao de contexto trabalha em conjunto com:

Tool Result Budget

O orcamento de resultados e a primeira linha de defesa. A recuperacao ativa quando o orcamento nao foi suficiente.

Microcompactacao

A compactacao progressiva reduz o crescimento do contexto ao longo do tempo.

Controle de Conversa

O comando /compact e a forma proativa de prevenir overflow.

Cost Tracking

Monitore o uso de contexto para antecipar quando /compact sera necessario.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Recuperacao de Contexto