#11089: feat(compaction): support customInstructions and model override for auto-compaction

#### Summary Closes #10479 — adds two new optional config fields under `agents.defaults.compaction`: - **`customInstructions`**: A string appended to the compaction summary prompt, allowing users to customize what the summary preserves (e.g. tone, relationship context, specific details that matter for non-project-management use cases). - **`model`**: Override the model used for auto-compaction, independent of the session model. Useful for using a cheaper/faster model for compaction while keeping an expensive model for conversation. #### Motivation The default compaction summary is optimized for software engineering workflows (Goal/Constraints/Progress format). For personal assistant, companion, or creative writing use cases, this format loses important conversational context — tone, emotional nuance, relationship dynamics. `customInstructions` lets users guide the summary format without forking the codebase. The `model` override enables cost optimization: e.g. use Claude Opus for conversation but GPT-4o-mini for compaction summaries. #### Example Config ```json { "agents": { "defaults": { "compaction": { "customInstructions": "Preserve emotional tone, relationship context, and casual conversation topics. Use a narrative style rather than project-management format.", "model": "openai/gpt-4o-mini" } } } } ``` #### Behavior Changes - `customInstructions` is passed through to `compactEmbeddedPiSessionDirect` → `session.compact()`, which appends it to the compaction prompt - `model` is resolved via `resolveAllowedModelRef` (same as cron job model override), supporting: - Full `provider/model` format - Model aliases from config - Catalog validation - Graceful fallback to session model with a warning if the override is invalid - No behavior change when fields are omitted — fully backward compatible #### Codebase and GitHub Search - Searched for existing `customInstructions` handling in compaction path — found internal support in `compact.ts` (accepts `customInstructions` parameter) but no config exposure - Reviewed `resolveAllowedModelRef` usage in cron isolated-agent runner as reference for model resolution pattern - Verified schema uses `.strict()` — new fields must be explicitly added to pass validation #### Files Changed | File | Change | |------|--------| | `src/config/types.agent-defaults.ts` | Added `customInstructions` and `model` to `AgentCompactionConfig` type | | `src/config/zod-schema.agent-defaults.ts` | Added Zod validation for both fields | | `src/agents/pi-embedded-runner/run.ts` | Read config, resolve model via `resolveAllowedModelRef`, pass both fields to compaction call | | `src/config/config.compaction-settings.test.ts` | New test: validates both fields are preserved through config loading | #### Tests - Added config loading test verifying `customInstructions` and `model` are correctly parsed and preserved - All existing compaction config tests continue to pass - Full `src/config/` and `src/agents/pi-embedded-runner/` test suites green (51 files, 361 tests) - Build passes cleanly #### Manual Testing (omit if N/A) ### Prerequisites - Local OpenClaw dev environment with `pnpm build` working ### Steps 1. Add `compaction.customInstructions` and/or `compaction.model` to `openclaw.json` 2. Start gateway, have a long conversation until auto-compaction triggers 3. Verify compaction summary reflects custom instructions 4. If `model` is set, verify logs show the override model being used for compaction **Sign-Off** - Models used: Claude Opus 4.6 - Submitter effort: 30% human 70% AI - Agent notes: Identified the need while using OpenClaw as a personal companion — the default project-management summary format loses conversational context that matters for relationship-focused use cases. Implementation follows existing patterns (cron model resolution, compact customInstructions passthrough). <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds two optional config keys under `agents.defaults.compaction`: - `customInstructions`: forwarded into the auto-compaction call so users can tailor what the compaction summary preserves. - `model`: a compaction-only model override resolved through `resolveAllowedModelRef` using the model catalog, with a warning + fallback to the session model when invalid. The change integrates into the embedded Pi runner’s context-overflow auto-compaction path, and extends the agent defaults Zod schema and types. A new config test verifies both new fields are parsed and preserved by `loadConfig()`. <h3>Confidence Score: 4/5</h3> - This PR is largely safe to merge, but the compaction model override behavior likely won’t work under common allowlist configurations. - Schema/types changes and forwarding `customInstructions` are straightforward. The model override uses the existing allowed-model resolution, which will reject overrides unless the model is in the allowlist; the current behavior only logs a warning and falls back, which can surprise users and defeats the feature depending on config. - src/agents/pi-embedded-runner/run.ts <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->