#14330: feat(compaction): structured summary template for safeguard mode

## Problem Freeform summarization during compaction silently drops specific data: URLs, IDs, file paths, credentials, and config values. This causes context loss that users may not notice until critical information is gone. ## Solution Add an optional structured template for safeguard-mode compaction summaries. When `agents.defaults.compaction.structuredSummary` is enabled (`false` by default), the summarizer receives mandatory sections: - **Goal** — What the user is trying to accomplish - **Progress** — What has been done so far - **Key Data** — ALL URLs, IDs, tokens, credentials, config values - **Decisions** — Key decisions and their reasoning - **Modified Files** — Files read, written, or modified - **Next Steps** — What needs to happen next - **Constraints** — Active constraints or blockers Each section must be populated or explicitly marked 'None.' This acts as a checklist that prevents silent information loss. ## Motivation Factory.ai research (Dec 2025) showed structured summaries score **4.8/5** vs **3.2/5** for freeform in information preservation. The key insight: *structure forces preservation* — mandatory sections act as a checklist the model cannot skip. References: - [Factory.ai: Evaluating Compression](https://factory.ai/news/evaluating-compression) - [Phil Schmid: Context Engineering Part 2](https://www.philschmid.de/context-engineering-part-2) - Related: #2597 (context/state lost after compaction) ## Changes | File | Change | |------|--------| | `src/agents/pi-extensions/compaction-safeguard.ts` | Template injection logic | | `src/agents/pi-extensions/compaction-safeguard-runtime.ts` | Runtime type | | `src/agents/pi-extensions/compaction-safeguard.test.ts` | 22 new behavior tests | | `src/agents/pi-embedded-runner/extensions.ts` | Pass structuredSummary flag | | `src/config/types.agent-defaults.ts` | Type definition | | `src/config/zod-schema.agent-defaults.ts` | Zod schema | | `src/config/config.compaction-settings.test.ts` | Config schema tests | | `docs/gateway/configuration-reference.md` | Documentation | ## Testing - **28/28 tests pass** (3 config + 25 safeguard behavior tests) - Build passes cleanly - Feature is opt-in (default: `false`) — zero impact on existing users ## Usage ```json5 { agents: { defaults: { compaction: { mode: "safeguard", structuredSummary: true, }, }, }, } ``` > **Warning:** When enabled, the template instructs the model to retain URLs, IDs, tokens, credentials, and config values verbatim in the persisted compaction summary. Enable only for trusted environments. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> Adds an opt-in `structuredSummary` boolean to safeguard-mode compaction that injects a mandatory-section template (Goal, Progress, Key Data, Decisions, Modified Files, Next Steps, Constraints) into the summarizer's instructions, preventing silent data loss during context compaction. - New `STRUCTURED_SUMMARY_TEMPLATE` constant prepended to both main and split-turn prefix summarization instructions when enabled - `prependInstructions` helper composes the template with existing custom instructions - Config plumbing through Zod schema, TypeScript types, runtime registry, and extension wiring - Feature is opt-in (`false` by default) and only active when `mode: "safeguard"` — zero impact on existing users - 22 new behavior tests cover enabled/disabled paths, split-turn handling, template content, and config round-tripping - Documentation updated with config example and security warning about verbatim credential retention <h3>Confidence Score: 4/5</h3> - This PR is safe to merge — it's an opt-in, well-gated feature addition with no impact on existing behavior. - The feature is off by default, only active in safeguard mode, and the implementation is straightforward (template string injection). All changes are consistent across schema, types, runtime, and logic layers. Test coverage is thorough. The only consideration is the security implication of retaining credentials verbatim, which is clearly documented. - No files require special attention. <!-- greptile_other_comments_section --> _{(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!} <!-- /greptile_comment -->