[peyton-alt]

https://entire.io/gh/entireio/cli/trails/1600

Problem

For external agents, a checkpoint's transcript.jsonl (Entire's shared transcript format) is built by the CLI's built-in compactor, which only understands built-in agents' native formats. For agents like Grok Build (entire-agent-grok) it writes empty lines (four blank user entries for a full session), so nothing downstream can show the conversation. The agent's own compact-transcript command, which does understand its format, was only used by entire explain.

Fix

When the session's agent declares compact_transcript, writeCompactTranscript (cmd/entire/cli/checkpoint/persistent.go, new compact_agent.go) builds transcript.jsonl with the agent's compactor:

• feeds it the already-redacted transcript through a private temp file, and redacts its output again (the plugin is outside the redaction pipeline)
• keeps checkpoint scoping: compact_transcript_start is the number of leading lines that compacting the lines before checkpoint_transcript_start shares byte-for-byte with the full output, so a line the plugin merges across the boundary (e.g. Grok folding a tool_result into its call) stays in this checkpoint
• gives each compactor run its own 5 s timeout, because they happen inside the checkpoint ref lock; a slow or hung plugin falls back instead of stalling other checkpoint writes, and a timed-out prefix run is logged rather than treated as not compactable
• allows compact-transcript stdout up to the base64 size of the 50 MB compact blob cap (other subcommands keep 10 MB), so large sessions don't fall back to a blank transcript
• returns a content-free error on plugin failure, so plugin stderr (which may carry transcript text) never reaches the logs
• falls back to the built-in compactor when the agent errors, returns nothing, returns assets, or its output fails redaction, so a checkpoint is never blocked

Docs: compact_transcript / compact-transcript added to external-agent-protocol.md (it was undocumented); checkpoint-implementation.md describes the agent path and fallbacks.

+524/-8 across 8 files (the protocol doc now also says compact-transcript may receive a CLI temp file outside the agent's session store).

Verification

• New tests in persistent_external_compact_test.go with a mock external agent: agent compactor used with correct scoping; a plugin that merges lines across the boundary keeps the merged line in scope; a hung plugin times out and falls back; each run gets its own timeout; plugin stderr stays out of errors; fallback on compactor failure, empty output and returned assets; prefix-compaction failure keeps the agent's transcript and scopes from line 0; credential in agent output redacted before storing; unit tests for leadingLines / countLines. The scoping and redaction tests failed before the change.
• Real Grok Build session through store.Write with the real entire-agent-grok: transcript.jsonl went from 4 blank lines to 53 lines including the prompt.
• End to end on a local stack: six Grok Build sessions committed with this build; together with the entire-api fallback to transcript.jsonl, the session page shows the prompt, responses and tool calls.
• Compared against every external agent in entireio/external-agents that declares compact_transcript, using each agent's sample transcripts and the real binaries through compactWithAgent: the agent compactor was never worse. Built-in output was empty or blank for Goose, Kilo, Kiro, Amp (legacy export) and Grok Build; Oh My Pi and Qwen gain tool calls; Amp (current format) is unchanged; Hermes's compactor rejects the temp path and falls back to the built-in result (same as today). 4–76 ms per checkpoint.
• mise run lint: 0 issues. mise run test:ci passes (run with ~/.local/bin off PATH, since a real entire-agent-* there leaks into setup tests).

Fixes the bug in trail https://entire.io/gh/entireio/cli/trails/1608. Pairs with entire-api trail https://entire.io/et/entirehq/entire-api/trails/400, which reads transcript.jsonl for agents it has no parser for. Checkpoints written before this fix keep their empty transcript.jsonl.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Boundary calculation can omit checkpoint content, and plugin error logging can expose sensitive data.

2 open findings

• Plugin stderr can leak secrets into logs · New
• Merged fragments can skip new content at checkpoint boundaries · New

What changed in this PR

Enables checkpoint storage to use external agents’ own compactors so their conversations appear in transcript.jsonl.

Changes:

• Adds agent compaction with output redaction and built-in fallback.
• Adds tests for scoping, failures, assets, and credential redaction.
• Documents the compaction protocol and persistence behavior.

File	Description
docs/​development/​checkpoint-implementation.md	Documents agent compaction and fallbacks.
docs/​architecture/​external-agent-protocol.md	Defines the compaction capability and command.
cmd/​entire/​cli/​checkpoint/​persistent.go	Tries agent compaction before built-in conversion.
cmd/​entire/​cli/​checkpoint/​persistent_external_compact_test.go	Tests external compaction and safeguards.
cmd/​entire/​cli/​checkpoint/​compact_agent.go	Implements compaction, redaction, and boundary calculation.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1bc3daa. Configure here.}