Honesty rails: usage, errors, sessions, auth
Fail closed where the protocol is incomplete or Factory cannot preserve the state atomically.
Pinned upstream commit: b189869b7755d2b482969acf6c92da3ecfeffd36
- Map complete token fields without double-counting cache reads.
- Explain why sessionId can be kept while incomplete usage is omitted.
- Defend fail-closed resume/fork and external credential ownership.
The big idea
A useful provider must be honest about what it cannot know. It reports token usage only when Grok says the snapshot is complete. It surfaces documented errors. It refuses resume and fork because a Grok session is a coordinated directory, not one file. It accepts credentials only through the external CLI's normal environment/login boundary.
Think of it like… Think of a sealed evidence bag: if one required item is missing or the seal is broken, label it incomplete instead of guessing the contents. It breaks because some protocol fields can still be used safely while others are omitted.
Headless usage treats `input_tokens` as uncached input and reports cache reads separately. The adapter maps cache creation to zero because that field is not part of the terminal event shape it consumes. If `usage_is_incomplete` is true, it emits sessionId but no usage event.
Grok stores `summary.json`, `updates.jsonl`, `chat_history.jsonl`, plan, rewind points, signals, feedback, compaction checkpoints, and subagent metadata under one session directory. Factory's present capture abstraction is file-shaped, so pretending it can resume would lose coordinated state. `captureSessions:false` and a thrown resume/fork error are correctness features.
Evidence: Pinned session management guide
Compare the boundaries
Safe: preserve known metadata and omit the incomplete claim.
Risky: report zeros, copy one JSONL, or embed a credential literal.
| Surface | Upstream | Alembic | Verdict |
|---|---|---|---|
| Complete usage | All required token fields present | Emit mapped usage | REPORT |
| Incomplete usage | `usage_is_incomplete:true` | Keep session; omit usage | OMIT |
| Resume/fork | Upstream directory can resume | No atomic directory seam yet | FAIL CLOSED |
Grok stores `summary.json`, `updates.jsonl`, `chat_history.jsonl`, plan, rewind points, signals, feedback, compaction checkpoints, and subagent metadata under one session directory. Factory's present capture abstraction is file-shaped, so pretending it can resume would lose coordinated state. `captureSessions:false` and a thrown resume/fork error are correctness features.
Real code and commands
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 …");
}How to reach it
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}.mdEvidence: RESOURCES.md
Visual atlas
Practice and feedback
Usage is incomplete but sessionId is present. What can the provider emit?
Retrieval cards
Inject a boundary fault
Choose a fault and inspect the honest provider response.
Four-slide summary
Check your model
Why is `captureSessions` false in phase one?