feat(hooks): emit compaction lifecycle hooks (openclaw#16788)

vincentkoc · web-flow · commit 71ec42127d8f · 2026-03-05T19:08:26.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,7 @@ Docs: https://docs.openclaw.ai
 - Plugins/hook policy: add `plugins.entries.<id>.hooks.allowPromptInjection`, validate unknown typed hook names at runtime, and preserve legacy `before_agent_start` model/provider overrides while stripping prompt-mutating fields when prompt injection is disabled. (#36567) thanks @gumadeiras.
 - Tools/Diffs guidance: restore a short system-prompt hint for enabled diffs while keeping the detailed instructions in the companion skill, so diffs usage guidance stays out of user-prompt space. (#36904) thanks @gumadeiras.
 - Telegram/ACP topic bindings: accept Telegram Mac Unicode dash option prefixes in `/acp spawn`, support Telegram topic thread binding (`--thread here|auto`), route bound-topic follow-ups to ACP sessions, add actionable Telegram approval buttons with prefixed approval-id resolution, and pin successful bind confirmations in-topic. (#36683) Thanks @huntharo.
+- Hooks/Compaction lifecycle: emit `session:compact:before` and `session:compact:after` internal events plus plugin compaction callbacks with session/count metadata, so automations can react to compaction runs consistently. (#16788) thanks @vincentkoc.
 
 ### Breaking
 
diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md
@@ -243,6 +243,14 @@ Triggered when agent commands are issued:
 - **`command:reset`**: When `/reset` command is issued
 - **`command:stop`**: When `/stop` command is issued
 
+### Session Events
+
+- **`session:compact:before`**: Right before compaction summarizes history
+- **`session:compact:after`**: After compaction completes with summary metadata
+
+Internal hook payloads emit these as `type: "session"` with `action: "compact:before"` / `action: "compact:after"`; listeners subscribe with the combined keys above.
+Specific handler registration uses the literal key format `${type}:${action}`. For these events, register `session:compact:before` and `session:compact:after`.
+
 ### Agent Events
 
 - **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)
@@ -351,6 +359,13 @@ These hooks are not event-stream listeners; they let plugins synchronously adjus
 
 - **`tool_result_persist`**: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or `undefined` to keep it as-is. See [Agent Loop](/concepts/agent-loop).
 
+### Plugin Hook Events
+
+Compaction lifecycle hooks exposed through the plugin hook runner:
+
+- **`before_compaction`**: Runs before compaction with count/token metadata
+- **`after_compaction`**: Runs after compaction with compaction summary metadata
+
 ### Future Events
 
 Planned event types:
diff --git a/src/agents/pi-embedded-runner/compact.hooks.test.ts b/src/agents/pi-embedded-runner/compact.hooks.test.ts
@@ -0,0 +1,357 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { hookRunner, triggerInternalHook, sanitizeSessionHistoryMock } = vi.hoisted(() => ({
+  hookRunner: {
+    hasHooks: vi.fn(),
+    runBeforeCompaction: vi.fn(),
+    runAfterCompaction: vi.fn(),
+  },
+  triggerInternalHook: vi.fn(),
+  sanitizeSessionHistoryMock: vi.fn(async (params: { messages: unknown[] }) => params.messages),
+}));
+
+vi.mock("../../plugins/hook-runner-global.js", () => ({
+  getGlobalHookRunner: () => hookRunner,
+}));
+
+vi.mock("../../hooks/internal-hooks.js", async () => {
+  const actual = await vi.importActual<typeof import("../../hooks/internal-hooks.js")>(
+    "../../hooks/internal-hooks.js",
+  );
+  return {
+    ...actual,
+    triggerInternalHook,
+  };
+});
+
+vi.mock("@mariozechner/pi-coding-agent", () => {
+  return {
+    createAgentSession: vi.fn(async () => {
+      const session = {
+        sessionId: "session-1",
+        messages: [
+          { role: "user", content: "hello", timestamp: 1 },
+          { role: "assistant", content: [{ type: "text", text: "hi" }], timestamp: 2 },
+          {
+            role: "toolResult",
+            toolCallId: "t1",
+            toolName: "exec",
+            content: [{ type: "text", text: "output" }],
+            isError: false,
+            timestamp: 3,
+          },
+        ],
+        agent: {
+          replaceMessages: vi.fn((messages: unknown[]) => {
+            session.messages = [...(messages as typeof session.messages)];
+          }),
+          streamFn: vi.fn(),
+        },
+        compact: vi.fn(async () => {
+          // simulate compaction trimming to a single message
+          session.messages.splice(1);
+          return {
+            summary: "summary",
+            firstKeptEntryId: "entry-1",
+            tokensBefore: 120,
+            details: { ok: true },
+          };
+        }),
+        dispose: vi.fn(),
+      };
+      return { session };
+    }),
+    SessionManager: {
+      open: vi.fn(() => ({})),
+    },
+    SettingsManager: {
+      create: vi.fn(() => ({})),
+    },
+    estimateTokens: vi.fn(() => 10),
+  };
+});
+
+vi.mock("../session-tool-result-guard-wrapper.js", () => ({
+  guardSessionManager: vi.fn(() => ({
+    flushPendingToolResults: vi.fn(),
+  })),
+}));
+
+vi.mock("../pi-settings.js", () => ({
+  ensurePiCompactionReserveTokens: vi.fn(),
+  resolveCompactionReserveTokensFloor: vi.fn(() => 0),
+}));
+
+vi.mock("../models-config.js", () => ({
+  ensureOpenClawModelsJson: vi.fn(async () => {}),
+}));
+
+vi.mock("../model-auth.js", () => ({
+  getApiKeyForModel: vi.fn(async () => ({ apiKey: "test", mode: "env" })),
+  resolveModelAuthMode: vi.fn(() => "env"),
+}));
+
+vi.mock("../sandbox.js", () => ({
+  resolveSandboxContext: vi.fn(async () => null),
+}));
+
+vi.mock("../session-file-repair.js", () => ({
+  repairSessionFileIfNeeded: vi.fn(async () => {}),
+}));
+
+vi.mock("../session-write-lock.js", () => ({
+  acquireSessionWriteLock: vi.fn(async () => ({ release: vi.fn(async () => {}) })),
+  resolveSessionLockMaxHoldFromTimeout: vi.fn(() => 0),
+}));
+
+vi.mock("../bootstrap-files.js", () => ({
+  makeBootstrapWarn: vi.fn(() => () => {}),
+  resolveBootstrapContextForRun: vi.fn(async () => ({ contextFiles: [] })),
+}));
+
+vi.mock("../docs-path.js", () => ({
+  resolveOpenClawDocsPath: vi.fn(async () => undefined),
+}));
+
+vi.mock("../channel-tools.js", () => ({
+  listChannelSupportedActions: vi.fn(() => undefined),
+  resolveChannelMessageToolHints: vi.fn(() => undefined),
+}));
+
+vi.mock("../pi-tools.js", () => ({
+  createOpenClawCodingTools: vi.fn(() => []),
+}));
+
+vi.mock("./google.js", () => ({
+  logToolSchemasForGoogle: vi.fn(),
+  sanitizeSessionHistory: sanitizeSessionHistoryMock,
+  sanitizeToolsForGoogle: vi.fn(({ tools }: { tools: unknown[] }) => tools),
+}));
+
+vi.mock("./tool-split.js", () => ({
+  splitSdkTools: vi.fn(() => ({ builtInTools: [], customTools: [] })),
+}));
+
+vi.mock("../transcript-policy.js", () => ({
+  resolveTranscriptPolicy: vi.fn(() => ({
+    allowSyntheticToolResults: false,
+    validateGeminiTurns: false,
+    validateAnthropicTurns: false,
+  })),
+}));
+
+vi.mock("./extensions.js", () => ({
+  buildEmbeddedExtensionFactories: vi.fn(() => []),
+}));
+
+vi.mock("./history.js", () => ({
+  getDmHistoryLimitFromSessionKey: vi.fn(() => undefined),
+  limitHistoryTurns: vi.fn((msgs: unknown[]) => msgs.slice(0, 2)),
+}));
+
+vi.mock("../skills.js", () => ({
+  applySkillEnvOverrides: vi.fn(() => () => {}),
+  applySkillEnvOverridesFromSnapshot: vi.fn(() => () => {}),
+  loadWorkspaceSkillEntries: vi.fn(() => []),
+  resolveSkillsPromptForRun: vi.fn(() => undefined),
+}));
+
+vi.mock("../agent-paths.js", () => ({
+  resolveOpenClawAgentDir: vi.fn(() => "/tmp"),
+}));
+
+vi.mock("../agent-scope.js", () => ({
+  resolveSessionAgentIds: vi.fn(() => ({ defaultAgentId: "main", sessionAgentId: "main" })),
+}));
+
+vi.mock("../date-time.js", () => ({
+  formatUserTime: vi.fn(() => ""),
+  resolveUserTimeFormat: vi.fn(() => ""),
+  resolveUserTimezone: vi.fn(() => ""),
+}));
+
+vi.mock("../defaults.js", () => ({
+  DEFAULT_MODEL: "fake-model",
+  DEFAULT_PROVIDER: "openai",
+}));
+
+vi.mock("../utils.js", () => ({
+  resolveUserPath: vi.fn((p: string) => p),
+}));
+
+vi.mock("../../infra/machine-name.js", () => ({
+  getMachineDisplayName: vi.fn(async () => "machine"),
+}));
+
+vi.mock("../../config/channel-capabilities.js", () => ({
+  resolveChannelCapabilities: vi.fn(() => undefined),
+}));
+
+vi.mock("../../utils/message-channel.js", () => ({
+  normalizeMessageChannel: vi.fn(() => undefined),
+}));
+
+vi.mock("../pi-embedded-helpers.js", () => ({
+  ensureSessionHeader: vi.fn(async () => {}),
+  validateAnthropicTurns: vi.fn((m: unknown[]) => m),
+  validateGeminiTurns: vi.fn((m: unknown[]) => m),
+}));
+
+vi.mock("../pi-project-settings.js", () => ({
+  createPreparedEmbeddedPiSettingsManager: vi.fn(() => ({
+    getGlobalSettings: vi.fn(() => ({})),
+  })),
+}));
+
+vi.mock("./sandbox-info.js", () => ({
+  buildEmbeddedSandboxInfo: vi.fn(() => undefined),
+}));
+
+vi.mock("./model.js", () => ({
+  buildModelAliasLines: vi.fn(() => []),
+  resolveModel: vi.fn(() => ({
+    model: { provider: "openai", api: "responses", id: "fake", input: [] },
+    error: null,
+    authStorage: { setRuntimeApiKey: vi.fn() },
+    modelRegistry: {},
+  })),
+}));
+
+vi.mock("./session-manager-cache.js", () => ({
+  prewarmSessionFile: vi.fn(async () => {}),
+  trackSessionManagerAccess: vi.fn(),
+}));
+
+vi.mock("./system-prompt.js", () => ({
+  applySystemPromptOverrideToSession: vi.fn(),
+  buildEmbeddedSystemPrompt: vi.fn(() => ""),
+  createSystemPromptOverride: vi.fn(() => () => ""),
+}));
+
+vi.mock("./utils.js", () => ({
+  describeUnknownError: vi.fn((err: unknown) => String(err)),
+  mapThinkingLevel: vi.fn(() => "off"),
+  resolveExecToolDefaults: vi.fn(() => undefined),
+}));
+
+import { compactEmbeddedPiSessionDirect } from "./compact.js";
+
+const sessionHook = (action: string) =>
+  triggerInternalHook.mock.calls.find(
+    (call) => call[0]?.type === "session" && call[0]?.action === action,
+  )?.[0];
+
+describe("compactEmbeddedPiSessionDirect hooks", () => {
+  beforeEach(() => {
+    triggerInternalHook.mockClear();
+    hookRunner.hasHooks.mockReset();
+    hookRunner.runBeforeCompaction.mockReset();
+    hookRunner.runAfterCompaction.mockReset();
+    sanitizeSessionHistoryMock.mockReset();
+    sanitizeSessionHistoryMock.mockImplementation(async (params: { messages: unknown[] }) => {
+      return params.messages;
+    });
+  });
+
+  it("emits internal + plugin compaction hooks with counts", async () => {
+    hookRunner.hasHooks.mockReturnValue(true);
+    let sanitizedCount = 0;
+    sanitizeSessionHistoryMock.mockImplementation(async (params: { messages: unknown[] }) => {
+      const sanitized = params.messages.slice(1);
+      sanitizedCount = sanitized.length;
+      return sanitized;
+    });
+
+    const result = await compactEmbeddedPiSessionDirect({
+      sessionId: "session-1",
+      sessionKey: "agent:main:session-1",
+      sessionFile: "/tmp/session.jsonl",
+      workspaceDir: "/tmp",
+      messageChannel: "telegram",
+      customInstructions: "focus on decisions",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(sessionHook("compact:before")).toMatchObject({
+      type: "session",
+      action: "compact:before",
+    });
+    const beforeContext = sessionHook("compact:before")?.context;
+    const afterContext = sessionHook("compact:after")?.context;
+
+    expect(beforeContext).toMatchObject({
+      messageCount: 2,
+      tokenCount: 20,
+      messageCountOriginal: sanitizedCount,
+      tokenCountOriginal: sanitizedCount * 10,
+    });
+    expect(afterContext).toMatchObject({
+      messageCount: 1,
+      compactedCount: 1,
+    });
+    expect(afterContext?.compactedCount).toBe(
+      (beforeContext?.messageCountOriginal as number) - (afterContext?.messageCount as number),
+    );
+
+    expect(hookRunner.runBeforeCompaction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        messageCount: 2,
+        tokenCount: 20,
+      }),
+      expect.objectContaining({ sessionKey: "agent:main:session-1", messageProvider: "telegram" }),
+    );
+    expect(hookRunner.runAfterCompaction).toHaveBeenCalledWith(
+      {
+        messageCount: 1,
+        tokenCount: 10,
+        compactedCount: 1,
+      },
+      expect.objectContaining({ sessionKey: "agent:main:session-1", messageProvider: "telegram" }),
+    );
+  });
+
+  it("uses sessionId as hook session key fallback when sessionKey is missing", async () => {
+    hookRunner.hasHooks.mockReturnValue(true);
+
+    const result = await compactEmbeddedPiSessionDirect({
+      sessionId: "session-1",
+      sessionFile: "/tmp/session.jsonl",
+      workspaceDir: "/tmp",
+      customInstructions: "focus on decisions",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(sessionHook("compact:before")?.sessionKey).toBe("session-1");
+    expect(sessionHook("compact:after")?.sessionKey).toBe("session-1");
+    expect(hookRunner.runBeforeCompaction).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.objectContaining({ sessionKey: "session-1" }),
+    );
+    expect(hookRunner.runAfterCompaction).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.objectContaining({ sessionKey: "session-1" }),
+    );
+  });
+
+  it("applies validated transcript before hooks even when it becomes empty", async () => {
+    hookRunner.hasHooks.mockReturnValue(true);
+    sanitizeSessionHistoryMock.mockResolvedValue([]);
+
+    const result = await compactEmbeddedPiSessionDirect({
+      sessionId: "session-1",
+      sessionKey: "agent:main:session-1",
+      sessionFile: "/tmp/session.jsonl",
+      workspaceDir: "/tmp",
+      customInstructions: "focus on decisions",
+    });
+
+    expect(result.ok).toBe(true);
+    const beforeContext = sessionHook("compact:before")?.context;
+    expect(beforeContext).toMatchObject({
+      messageCountOriginal: 0,
+      tokenCountOriginal: 0,
+      messageCount: 0,
+      tokenCount: 0,
+    });
+  });
+});
diff --git a/src/agents/pi-embedded-runner/compact.ts b/src/agents/pi-embedded-runner/compact.ts
