From 72b6a11a832b73c9f68db09726e291bbc358fe71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=A0=95=EC=9A=B0=EC=9A=A9?= <71975659+keepitmello@users.noreply.github.com> Date: Fri, 13 Mar 2026 23:40:32 +0900 Subject: [PATCH] fix: preserve persona and language continuity in compaction summaries (#10456) Merged via squash. Prepared head SHA: 4518fb20e1037f87493e3668621cb1a45ab8233e Co-authored-by: keepitmello <71975659+keepitmello@users.noreply.github.com> Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com> Reviewed-by: @jalehman --- CHANGELOG.md | 3 + src/agents/pi-embedded-runner/extensions.ts | 1 + .../compaction-instructions.test.ts | 237 ++++++++++++++++++ .../pi-extensions/compaction-instructions.ts | 68 +++++ .../compaction-safeguard-runtime.ts | 1 + .../pi-extensions/compaction-safeguard.ts | 15 +- src/config/types.agent-defaults.ts | 2 + src/config/zod-schema.agent-defaults.ts | 1 + 8 files changed, 326 insertions(+), 2 deletions(-) create mode 100644 src/agents/pi-extensions/compaction-instructions.test.ts create mode 100644 src/agents/pi-extensions/compaction-instructions.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 43247ddf461..34c7cab869f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ Docs: https://docs.openclaw.ai ## Unreleased + ### Changes - Android/chat settings: redesign the chat settings sheet with grouped device and media sections, refresh the Connect and Voice tabs, and tighten the chat composer/session header for a denser mobile layout. (#44894) Thanks @obviyus. @@ -28,6 +29,8 @@ Docs: https://docs.openclaw.ai - Security/exec approvals: fail closed for Perl `-M` and `-I` approval flows so preload and load-path module resolution stays outside approval-backed runtime execution unless the operator uses a broader explicit trust path. - Control UI/insecure auth: preserve explicit shared token and password auth on plain-HTTP Control UI connects so LAN and reverse-proxy sessions no longer drop shared auth before the first WebSocket handshake. (#45088) Thanks @velvet-shark. - macOS/onboarding: avoid self-restarting freshly bootstrapped launchd gateways and give new daemon installs longer to become healthy, so `openclaw onboard --install-daemon` no longer false-fails on slower Macs and fresh VM snapshots. +- Agents/compaction: preserve safeguard compaction summary language continuity via default and configurable custom instructions so persona drift is reduced after auto-compaction. (#10456) Thanks @keepitmello. + ## 2026.3.12 ### Changes diff --git a/src/agents/pi-embedded-runner/extensions.ts b/src/agents/pi-embedded-runner/extensions.ts index 251063c6f19..08c1b0a3f70 100644 --- a/src/agents/pi-embedded-runner/extensions.ts +++ b/src/agents/pi-embedded-runner/extensions.ts @@ -84,6 +84,7 @@ export function buildEmbeddedExtensionFactories(params: { contextWindowTokens: contextWindowInfo.tokens, identifierPolicy: compactionCfg?.identifierPolicy, identifierInstructions: compactionCfg?.identifierInstructions, + customInstructions: compactionCfg?.customInstructions, qualityGuardEnabled: qualityGuardCfg?.enabled ?? false, qualityGuardMaxRetries: qualityGuardCfg?.maxRetries, model: params.model, diff --git a/src/agents/pi-extensions/compaction-instructions.test.ts b/src/agents/pi-extensions/compaction-instructions.test.ts new file mode 100644 index 00000000000..a75112d07cb --- /dev/null +++ b/src/agents/pi-extensions/compaction-instructions.test.ts @@ -0,0 +1,237 @@ +import { describe, expect, it } from "vitest"; +import { + DEFAULT_COMPACTION_INSTRUCTIONS, + resolveCompactionInstructions, + composeSplitTurnInstructions, +} from "./compaction-instructions.js"; + +describe("DEFAULT_COMPACTION_INSTRUCTIONS", () => { + it("is a non-empty string", () => { + expect(typeof DEFAULT_COMPACTION_INSTRUCTIONS).toBe("string"); + expect(DEFAULT_COMPACTION_INSTRUCTIONS.trim().length).toBeGreaterThan(0); + }); + + it("contains language preservation directive", () => { + expect(DEFAULT_COMPACTION_INSTRUCTIONS).toContain("primary language"); + }); + + it("contains factual content directive", () => { + expect(DEFAULT_COMPACTION_INSTRUCTIONS).toContain("factual content"); + }); + + it("does not exceed MAX_INSTRUCTION_LENGTH (800 chars)", () => { + expect(DEFAULT_COMPACTION_INSTRUCTIONS.length).toBeLessThanOrEqual(800); + }); +}); + +describe("resolveCompactionInstructions", () => { + describe("null / undefined handling", () => { + it("returns DEFAULT when both args are undefined", () => { + expect(resolveCompactionInstructions(undefined, undefined)).toBe( + DEFAULT_COMPACTION_INSTRUCTIONS, + ); + }); + + it("returns DEFAULT when both args are explicitly null (untyped JS caller)", () => { + expect( + resolveCompactionInstructions(null as unknown as undefined, null as unknown as undefined), + ).toBe(DEFAULT_COMPACTION_INSTRUCTIONS); + }); + }); + + describe("empty and whitespace normalization", () => { + it("treats empty-string event as absent -- runtime wins", () => { + const result = resolveCompactionInstructions("", "runtime value"); + expect(result).toBe("runtime value"); + }); + + it("treats whitespace-only event as absent -- runtime wins", () => { + const result = resolveCompactionInstructions(" ", "runtime value"); + expect(result).toBe("runtime value"); + }); + + it("treats tab/newline-only event as absent -- runtime wins", () => { + const result = resolveCompactionInstructions("\t\n\r", "runtime value"); + expect(result).toBe("runtime value"); + }); + + it("treats empty-string runtime as absent -- DEFAULT wins", () => { + const result = resolveCompactionInstructions(undefined, ""); + expect(result).toBe(DEFAULT_COMPACTION_INSTRUCTIONS); + }); + + it("treats whitespace-only runtime as absent -- DEFAULT wins", () => { + const result = resolveCompactionInstructions(undefined, " "); + expect(result).toBe(DEFAULT_COMPACTION_INSTRUCTIONS); + }); + + it("falls through to DEFAULT when both are empty strings", () => { + expect(resolveCompactionInstructions("", "")).toBe(DEFAULT_COMPACTION_INSTRUCTIONS); + }); + + it("falls through to DEFAULT when both are whitespace-only", () => { + expect(resolveCompactionInstructions(" ", "\t\n")).toBe(DEFAULT_COMPACTION_INSTRUCTIONS); + }); + + it("non-breaking space (\\u00A0) IS trimmed by ES2015+ trim() -- falls through", () => { + const nbsp = "\u00A0"; + const result = resolveCompactionInstructions(nbsp, "runtime"); + expect(result).toBe("runtime"); + }); + + it("KNOWN_EDGE: zero-width space (\\u200B) survives normalization -- invisible string used as instructions", () => { + const zws = "\u200B"; + const result = resolveCompactionInstructions(zws, "runtime"); + expect(result).toBe(zws); + }); + }); + + describe("precedence", () => { + it("event wins over runtime when both are non-empty", () => { + const result = resolveCompactionInstructions("event value", "runtime value"); + expect(result).toBe("event value"); + }); + + it("runtime wins when event is undefined", () => { + const result = resolveCompactionInstructions(undefined, "runtime value"); + expect(result).toBe("runtime value"); + }); + + it("event is trimmed before use", () => { + const result = resolveCompactionInstructions(" event ", "runtime"); + expect(result).toBe("event"); + }); + + it("runtime is trimmed before use", () => { + const result = resolveCompactionInstructions(undefined, " runtime "); + expect(result).toBe("runtime"); + }); + }); + + describe("truncation at 800 chars", () => { + it("does NOT truncate string of exactly 800 chars", () => { + const exact800 = "A".repeat(800); + const result = resolveCompactionInstructions(exact800, undefined); + expect(result).toHaveLength(800); + expect(result).toBe(exact800); + }); + + it("truncates string of 801 chars to 800", () => { + const over = "B".repeat(801); + const result = resolveCompactionInstructions(over, undefined); + expect(result).toHaveLength(800); + expect(result).toBe("B".repeat(800)); + }); + + it("truncates very long string to exactly 800", () => { + const huge = "C".repeat(5000); + const result = resolveCompactionInstructions(huge, undefined); + expect(result).toHaveLength(800); + }); + + it("truncation applies AFTER trimming -- 810 raw chars with 10 leading spaces yields 800", () => { + const padded = " ".repeat(10) + "D".repeat(800); + const result = resolveCompactionInstructions(padded, undefined); + expect(result).toHaveLength(800); + expect(result).toBe("D".repeat(800)); + }); + + it("truncation applies to runtime fallback as well", () => { + const longRuntime = "R".repeat(1000); + const result = resolveCompactionInstructions(undefined, longRuntime); + expect(result).toHaveLength(800); + }); + + it("truncates by code points, not code units (emoji safe)", () => { + const emojis801 = "\u{1F600}".repeat(801); + const result = resolveCompactionInstructions(emojis801, undefined); + expect(Array.from(result)).toHaveLength(800); + }); + + it("does not split surrogate pair when cut lands inside a pair", () => { + const input = "X" + "\u{1F600}".repeat(800); + const result = resolveCompactionInstructions(input, undefined); + const codePoints = Array.from(result); + expect(codePoints).toHaveLength(800); + expect(codePoints[0]).toBe("X"); + // Every code point in the truncated result must be a complete character (no lone surrogates) + for (const cp of codePoints) { + const code = cp.codePointAt(0)!; + const isLoneSurrogate = code >= 0xd800 && code <= 0xdfff; + expect(isLoneSurrogate).toBe(false); + } + }); + }); + + describe("return type", () => { + it("always returns a string, never undefined or null", () => { + const cases: [string | undefined, string | undefined][] = [ + [undefined, undefined], + ["", ""], + [" ", " "], + [null as unknown as undefined, null as unknown as undefined], + ["valid", undefined], + [undefined, "valid"], + ]; + + for (const [event, runtime] of cases) { + const result = resolveCompactionInstructions(event, runtime); + expect(typeof result).toBe("string"); + expect(result.length).toBeGreaterThan(0); + } + }); + }); +}); + +describe("composeSplitTurnInstructions", () => { + it("joins turn prefix, separator, and resolved instructions with double newlines", () => { + const result = composeSplitTurnInstructions("Turn prefix here", "Resolved instructions here"); + expect(result).toBe( + "Turn prefix here\n\nAdditional requirements:\n\nResolved instructions here", + ); + }); + + it("output contains the turn prefix verbatim", () => { + const prefix = "Summarize the last 5 messages."; + const result = composeSplitTurnInstructions(prefix, "Keep it short."); + expect(result).toContain(prefix); + }); + + it("output contains the resolved instructions verbatim", () => { + const instructions = "Write in Korean. Preserve persona."; + const result = composeSplitTurnInstructions("prefix", instructions); + expect(result).toContain(instructions); + }); + + it("output contains 'Additional requirements:' separator", () => { + const result = composeSplitTurnInstructions("a", "b"); + expect(result).toContain("Additional requirements:"); + }); + + it("KNOWN_EDGE: empty turnPrefix produces leading blank line", () => { + const result = composeSplitTurnInstructions("", "instructions"); + expect(result).toBe("\n\nAdditional requirements:\n\ninstructions"); + expect(result.startsWith("\n")).toBe(true); + }); + + it("KNOWN_EDGE: empty resolvedInstructions produces trailing blank area", () => { + const result = composeSplitTurnInstructions("prefix", ""); + expect(result).toBe("prefix\n\nAdditional requirements:\n\n"); + expect(result.endsWith("\n\n")).toBe(true); + }); + + it("does not deduplicate if instructions already contain 'Additional requirements:'", () => { + const instructions = "Additional requirements: keep it short."; + const result = composeSplitTurnInstructions("prefix", instructions); + const count = (result.match(/Additional requirements:/g) || []).length; + expect(count).toBe(2); + }); + + it("preserves multiline content in both inputs", () => { + const prefix = "Line 1\nLine 2"; + const instructions = "Rule A\nRule B\nRule C"; + const result = composeSplitTurnInstructions(prefix, instructions); + expect(result).toContain("Line 1\nLine 2"); + expect(result).toContain("Rule A\nRule B\nRule C"); + }); +}); diff --git a/src/agents/pi-extensions/compaction-instructions.ts b/src/agents/pi-extensions/compaction-instructions.ts new file mode 100644 index 00000000000..104cf6cb90b --- /dev/null +++ b/src/agents/pi-extensions/compaction-instructions.ts @@ -0,0 +1,68 @@ +/** + * Compaction instruction utilities. + * + * Provides default language-preservation instructions and a precedence-based + * resolver for customInstructions used during context compaction summaries. + */ + +/** + * Default instructions injected into every safeguard-mode compaction summary. + * Preserves conversation language and persona while keeping the SDK's required + * summary structure intact. + */ +export const DEFAULT_COMPACTION_INSTRUCTIONS = + "Write the summary body in the primary language used in the conversation.\n" + + "Focus on factual content: what was discussed, decisions made, and current state.\n" + + "Keep the required summary structure and section headers unchanged.\n" + + "Do not translate or alter code, file paths, identifiers, or error messages."; + +/** + * Upper bound on custom instruction length to prevent prompt bloat. + * ~800 chars ≈ ~200 tokens — keeps summarization quality stable. + */ +const MAX_INSTRUCTION_LENGTH = 800; + +function truncateUnicodeSafe(s: string, maxCodePoints: number): string { + const chars = Array.from(s); + if (chars.length <= maxCodePoints) { + return s; + } + return chars.slice(0, maxCodePoints).join(""); +} + +function normalize(s: string | undefined): string | undefined { + if (s == null) { + return undefined; + } + const trimmed = s.trim(); + return trimmed.length > 0 ? trimmed : undefined; +} + +/** + * Resolve compaction instructions with precedence: + * event (SDK) → runtime (config) → DEFAULT constant. + * + * Each input is normalized first (trim + empty→undefined) so that blank + * strings don't short-circuit the fallback chain. + */ +export function resolveCompactionInstructions( + eventInstructions: string | undefined, + runtimeInstructions: string | undefined, +): string { + const resolved = + normalize(eventInstructions) ?? + normalize(runtimeInstructions) ?? + DEFAULT_COMPACTION_INSTRUCTIONS; + return truncateUnicodeSafe(resolved, MAX_INSTRUCTION_LENGTH); +} + +/** + * Compose split-turn instructions by combining the SDK's turn-prefix + * instructions with the resolved compaction instructions. + */ +export function composeSplitTurnInstructions( + turnPrefixInstructions: string, + resolvedInstructions: string, +): string { + return [turnPrefixInstructions, "Additional requirements:", resolvedInstructions].join("\n\n"); +} diff --git a/src/agents/pi-extensions/compaction-safeguard-runtime.ts b/src/agents/pi-extensions/compaction-safeguard-runtime.ts index 0180689f864..42ccb90aa49 100644 --- a/src/agents/pi-extensions/compaction-safeguard-runtime.ts +++ b/src/agents/pi-extensions/compaction-safeguard-runtime.ts @@ -7,6 +7,7 @@ export type CompactionSafeguardRuntimeValue = { contextWindowTokens?: number; identifierPolicy?: AgentCompactionIdentifierPolicy; identifierInstructions?: string; + customInstructions?: string; /** * Model to use for compaction summarization. * Passed through runtime because `ctx.model` is undefined in the compact.ts workflow diff --git a/src/agents/pi-extensions/compaction-safeguard.ts b/src/agents/pi-extensions/compaction-safeguard.ts index 6012aed604d..4461b97d3e0 100644 --- a/src/agents/pi-extensions/compaction-safeguard.ts +++ b/src/agents/pi-extensions/compaction-safeguard.ts @@ -23,6 +23,10 @@ import { collectTextContentBlocks } from "../content-blocks.js"; import { wrapUntrustedPromptDataBlock } from "../sanitize-for-prompt.js"; import { repairToolUseResultPairing } from "../session-transcript-repair.js"; import { extractToolCallsFromAssistant, extractToolResultId } from "../tool-call-id.js"; +import { + composeSplitTurnInstructions, + resolveCompactionInstructions, +} from "./compaction-instructions.js"; import { getCompactionSafeguardRuntime } from "./compaction-safeguard-runtime.js"; const log = createSubsystemLogger("compaction-safeguard"); @@ -697,7 +701,7 @@ async function readWorkspaceContextForSummary(): Promise { export default function compactionSafeguardExtension(api: ExtensionAPI): void { api.on("session_before_compact", async (event, ctx) => { - const { preparation, customInstructions, signal } = event; + const { preparation, customInstructions: eventInstructions, signal } = event; if (!preparation.messagesToSummarize.some(isRealConversationMessage)) { log.warn( "Compaction safeguard: cancelling compaction with no real conversation messages to summarize.", @@ -715,6 +719,10 @@ export default function compactionSafeguardExtension(api: ExtensionAPI): void { // Model resolution: ctx.model is undefined in compact.ts workflow (extensionRunner.initialize() is never called). // Fall back to runtime.model which is explicitly passed when building extension paths. const runtime = getCompactionSafeguardRuntime(ctx.sessionManager); + const customInstructions = resolveCompactionInstructions( + eventInstructions, + runtime?.customInstructions, + ); const summarizationInstructions = { identifierPolicy: runtime?.identifierPolicy, identifierInstructions: runtime?.identifierInstructions, @@ -892,7 +900,10 @@ export default function compactionSafeguardExtension(api: ExtensionAPI): void { reserveTokens, maxChunkTokens, contextWindow: contextWindowTokens, - customInstructions: `${TURN_PREFIX_INSTRUCTIONS}\n\n${currentInstructions}`, + customInstructions: composeSplitTurnInstructions( + TURN_PREFIX_INSTRUCTIONS, + currentInstructions, + ), summarizationInstructions, previousSummary: undefined, }); diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts index 11d1809c86a..c81cf0edbed 100644 --- a/src/config/types.agent-defaults.ts +++ b/src/config/types.agent-defaults.ts @@ -307,6 +307,8 @@ export type AgentCompactionConfig = { reserveTokensFloor?: number; /** Max share of context window for history during safeguard pruning (0.1–0.9, default 0.5). */ maxHistoryShare?: number; + /** Additional compaction-summary instructions that can preserve language or persona continuity. */ + customInstructions?: string; /** Preserve this many most-recent user/assistant turns verbatim in compaction summary context. */ recentTurnsPreserve?: number; /** Identifier-preservation instruction policy for compaction summaries. */ diff --git a/src/config/zod-schema.agent-defaults.ts b/src/config/zod-schema.agent-defaults.ts index 02148736e2a..dfa7e23e1c1 100644 --- a/src/config/zod-schema.agent-defaults.ts +++ b/src/config/zod-schema.agent-defaults.ts @@ -91,6 +91,7 @@ export const AgentDefaultsSchema = z keepRecentTokens: z.number().int().positive().optional(), reserveTokensFloor: z.number().int().nonnegative().optional(), maxHistoryShare: z.number().min(0.1).max(0.9).optional(), + customInstructions: z.string().optional(), identifierPolicy: z .union([z.literal("strict"), z.literal("off"), z.literal("custom")]) .optional(),