Trilhos de honestidade: usage, errors, sessions, auth
Falhe de forma fechada onde o protocolo está incompleto ou a Factory não consegue preservar o estado atomicamente.
Commit upstream fixado: b189869b7755d2b482969acf6c92da3ecfeffd36
- Mapear campos completos de tokens sem contar cache reads duas vezes.
- Explicar por que sessionId pode ser mantido enquanto usage incompleto é omitido.
- Defender resume/fork fail-closed e propriedade externa de credenciais.
A grande ideia
Um provider útil precisa ser honesto sobre o que não consegue saber. Reporta usage de tokens apenas quando o Grok diz que o snapshot está completo. Expõe erros documentados. Recusa resume e fork porque uma sessão Grok é um diretório coordenado, não um arquivo. Aceita credenciais apenas pela fronteira normal de ambiente/login do CLI externo.
Pense como… Pense num saco lacrado de evidências: se um item obrigatório falta ou o lacre rompeu, marque como incompleto em vez de adivinhar o conteúdo. A analogia quebra porque alguns campos do protocolo ainda podem ser usados com segurança enquanto outros são omitidos.
O usage headless trata `input_tokens` como input não cacheado e reporta cache reads separadamente. O adapter mapeia cache creation para zero porque esse campo não faz parte da forma do evento terminal consumido. Se `usage_is_incomplete` for true, emite sessionId mas nenhum evento de usage.
O Grok armazena `summary.json`, `updates.jsonl`, `chat_history.jsonl`, plan, rewind points, signals, feedback, checkpoints de compaction e metadata de subagentes num diretório de sessão. A abstração atual de captura da Factory tem forma de arquivo, então fingir resume perderia estado coordenado. `captureSessions:false` e erro lançado em resume/fork são features de correção.
Evidência: Guia fixado de gerenciamento de sessões
Compare as fronteiras
Seguro: preservar metadata conhecida e omitir a afirmação incompleta.
Arriscado: reportar zeros, copiar um JSONL ou embutir credencial literal.
| Superfície | Upstream | Alembic | Veredito |
|---|---|---|---|
| Complete usage | Todos os campos de token presentes | Emitir usage mapeado | REPORT |
| Incomplete usage | `usage_is_incomplete:true` | Manter sessão; omitir usage | OMIT |
| Resume/fork | Diretório upstream pode resumir | Sem costura atômica de diretório | FAIL CLOSED |
O Grok armazena `summary.json`, `updates.jsonl`, `chat_history.jsonl`, plan, rewind points, signals, feedback, checkpoints de compaction e metadata de subagentes num diretório de sessão. A abstração atual de captura da Factory tem forma de arquivo, então fingir resume perderia estado coordenado. `captureSessions:false` e erro lançado em resume/fork são features de correção.
Código e comandos reais
packages/factory/src/GrokAgentProvider.ts
if (event.usage_is_incomplete !== true) {
const usage = parseGrokUsage(event.usage);
if (usage) parsed.push({ type: "usage", usage });
}
if (resumeSession || forkSession) {
throw new Error("Grok session resume/fork is not supported …");
}Como chegar lá
sed -n '20,150p' packages/factory/src/GrokAgentProvider.ts
rg -n "Storage Layout|usage_is_incomplete" /tmp/alembic-grok-build-20260716/crates/codegen/xai-grok-pager/docs/user-guide/{14-headless-mode,17-sessions}.mdEvidência: RESOURCES.md
Atlas visual
Prática e feedback
Usage está incompleto, mas sessionId está presente. O que o provider pode emitir?
Cartões de recuperação
Injete uma falha de fronteira
Escolha uma falha e veja a resposta honesta do provider.
Resumo em quatro slides
Teste seu modelo
Por que `captureSessions` é false na fase um?