feat(rawr): add RAWR post-turn auto-compaction policy and config

[mateicanavra]

External (non-OpenAI) Pull Request Requirements

Before opening this Pull Request, please read the dedicated "Contributing" markdown file or your PR may be closed:
https://github.com/openai/codex/blob/main/docs/contributing.md

RAWR automatic post-turn compaction policy

Adds a new rawr_auto_compaction configuration option and the supporting runtime logic that automatically triggers context compaction after a turn completes when the model's context window is running low.

Feature flag

A new RawrAutoCompaction feature flag (rawr_auto_compaction, stage: UnderDevelopment, off by default) gates all RAWR compaction behavior. Setting rawr_auto_compaction = true in config.toml enables the feature, or a structured [rawr_auto_compaction] table can be used for fine-grained control.

Configuration schema (RawrAutoCompactionToml)

The new config type accepts either a plain boolean or a structured object with the following fields:

• mode – tag, suggest, or auto (default auto). In tag/suggest mode a warning event is emitted instead of running compaction.
• packet_author – watcher (default) or agent. Controls who writes the post-compaction continuation context packet.
• scratch_write_enabled – when true, the agent is asked to write a scratchpad file before compaction so research notes survive history rewrite.
• compaction_model / compaction_reasoning_effort / compaction_verbosity – optional overrides for the compaction call.
• policy – per-tier thresholds and boundary requirements across four tiers: early, ready, asap, and emergency.

Default percent-remaining thresholds are 85 / 75 / 65 / 15 for early / ready / asap / emergency respectively.

Boundary signals

Each policy tier specifies which RawrAutoCompactionBoundary signals must be observed before compaction fires: commit, plan_checkpoint, plan_update, pr_checkpoint, agent_done, topic_shift, concluding_thought, and turn_complete. Emergency tier always fires unconditionally. Plan boundaries can optionally require a semantic break (plan_boundaries_require_semantic_break) before they count.

Runtime (rawr_auto_compaction.rs / rawr_prompts.rs)

• rawr_should_compact_at_turn_complete evaluates tier eligibility and boundary satisfaction.
• rawr_build_watcher_post_compact_packet constructs a structured continuation context packet injected as the first user message of the next turn.
• rawr_build_agent_continuation_packet_prompt combines scratch-write and packet prompts when packet_author = agent.
• Prompt templates are read from <codex_home>/auto-compact/auto-compact.md and scratch-write.md, with built-in defaults written on first use.
• Placeholder expansion ({scratchFile}, {threadId}, etc.) and YAML front-matter stripping are supported.
• Scratch file paths are derived from the session source or a deterministic name hashed from the thread ID.

Session integration

on_task_finished now accepts a TaskKind parameter. For TaskKind::Regular turns, maybe_run_rawr_post_turn_auto_compaction is called after the turn completes. It computes percent-remaining from total token usage and the configured model_context_window, selects the appropriate inline compact task (local or remote), and queues the handoff message for the next turn. Active-turn cleanup is deferred until after RAWR compaction runs.

Tests

• Integration test rawr_turn_complete_auto_compaction_emits_started_and_completed_items verifies that enabling the feature with a model_context_window set causes compaction started/completed items to be emitted after a turn that exceeds the threshold.
• Unit tests cover tier selection, boundary matching, tail truncation, placeholder expansion, and prompt file creation.

[mateicanavra]

• feat(rawr): add RAWR post-turn auto-compaction policy and config #29 👈 (View in Graphite)
• codex/integration-upstream-main

This stack of pull requests is managed by Graphite. Learn more about stacking.