fix(codex): start budget native compaction

Steady-ai · Steady-ai · commit 47f33748d4b6 · 2026-05-26T22:33:20.000-06:00
diff --git a/docs/plugins/codex-harness-runtime.md b/docs/plugins/codex-harness-runtime.md
@@ -214,9 +214,17 @@ history, search, `/new`, `/reset`, and future model or harness switching.
 
 Explicit compaction requests, such as `/compact` or a plugin-requested manual
 compact operation, start native Codex compaction with `thread/compact/start`.
+OpenClaw also starts native Codex compaction for the `budget` preflight trigger
+used by `agents.defaults.compaction.maxActiveTranscriptBytes`, because that
+trigger protects the local channel transcript mirror from growing without a
+native cleanup request. Other automatic triggers remain Codex-owned and are not
+started by OpenClaw.
+
 OpenClaw returns after starting that native operation. It does not wait for
 completion, impose a separate OpenClaw timeout, restart the shared Codex
 app-server, or record the operation as an OpenClaw-completed compaction.
+Operators debugging oversized transcript behavior can search gateway logs for
+`started codex app-server compaction` with `trigger: "budget"`.
 
 When a context engine requests Codex thread-bootstrap projection, OpenClaw
 projects tool-call names and ids, input shapes, and redacted tool-result content
diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md
@@ -354,7 +354,9 @@ OpenClaw also enforces a safety floor for embedded runs:
   string such as `"20mb"` to run local compaction before a turn when the active
   transcript gets large. This guard is active only when
   `truncateAfterCompaction` is also enabled. Leave it unset or set `0` to
-  disable.
+  disable. For Codex harness sessions, this preflight starts native Codex
+  compaction with `thread/compact/start` rather than replacing Codex compaction
+  with an OpenClaw summarizer.
 - When `agents.defaults.compaction.truncateAfterCompaction` is enabled,
   OpenClaw rotates the active transcript to a compacted successor JSONL after
   compaction. Branch/restore checkpoint actions use that compacted successor;
diff --git a/extensions/codex/src/app-server/compact.test.ts b/extensions/codex/src/app-server/compact.test.ts
@@ -126,7 +126,7 @@ describe("maybeCompactCodexAppServerSession", () => {
     expect(details.pending).toBe(true);
   });
 
-  it("skips native app-server compaction for automatic budget triggers", async () => {
+  it("starts native app-server compaction for automatic budget triggers", async () => {
     const fake = createFakeCodexClient();
     setCodexAppServerClientFactoryForTest(async () => fake.client);
     const sessionFile = await writeTestBinding();
@@ -142,16 +142,45 @@ describe("maybeCompactCodexAppServerSession", () => {
       }),
     );
 
+    expect(fake.request).toHaveBeenCalledWith("thread/compact/start", { threadId: "thread-1" });
+    expect(result.ok).toBe(true);
+    expect(result.compacted).toBe(false);
+    expect(result.reason).toBeUndefined();
+    expect(result.result?.tokensBefore).toBe(456);
+    expect(compactDetails(result)).toMatchObject({
+      backend: "codex-app-server",
+      threadId: "thread-1",
+      signal: "thread/compact/start",
+      pending: true,
+    });
+  });
+
+  it("skips native app-server compaction for overflow triggers", async () => {
+    const fake = createFakeCodexClient();
+    setCodexAppServerClientFactoryForTest(async () => fake.client);
+    const sessionFile = await writeTestBinding();
+
+    const result = requireCompactResult(
+      await maybeCompactCodexAppServerSession({
+        sessionId: "session-1",
+        sessionKey: "agent:main:session-1",
+        sessionFile,
+        workspaceDir: tempDir,
+        trigger: "overflow",
+        currentTokenCount: 654,
+      }),
+    );
+
     expect(fake.request).not.toHaveBeenCalled();
     expect(result.ok).toBe(true);
     expect(result.compacted).toBe(false);
     expect(result.reason).toBe("codex app-server owns automatic compaction");
-    expect(result.result?.tokensBefore).toBe(456);
+    expect(result.result?.tokensBefore).toBe(654);
     expect(compactDetails(result)).toMatchObject({
       backend: "codex-app-server",
       skipped: true,
       reason: "non_manual_trigger",
-      trigger: "budget",
+      trigger: "overflow",
     });
   });
 
diff --git a/extensions/codex/src/app-server/compact.ts b/extensions/codex/src/app-server/compact.ts
@@ -122,7 +122,10 @@ async function compactCodexNativeThread(
   params: CompactEmbeddedPiSessionParams,
   options: { pluginConfig?: unknown; clientFactory?: CodexAppServerClientFactory } = {},
 ): Promise<EmbeddedPiCompactResult | undefined> {
-  if (params.trigger !== "manual") {
+  // The transcript-byte budget preflight is an explicit OpenClaw request to
+  // shrink a large channel mirror; skipping it leaves long-lived Codex sessions
+  // above the configured local transcript guard.
+  if (params.trigger !== "manual" && params.trigger !== "budget") {
     embeddedAgentLog.info("skipping codex app-server compaction for non-manual trigger", {
       sessionId: params.sessionId,
       sessionKey: params.sessionKey,
@@ -185,6 +188,7 @@ async function compactCodexNativeThread(
     embeddedAgentLog.info("started codex app-server compaction", {
       sessionId: params.sessionId,
       threadId: binding.threadId,
+      trigger: params.trigger ?? "manual",
     });
   } catch (error) {
     if (isCodexThreadNotFoundError(error)) {
@@ -198,6 +202,7 @@ async function compactCodexNativeThread(
       sessionId: params.sessionId,
       sessionKey: params.sessionKey,
       threadId: binding.threadId,
+      trigger: params.trigger ?? "manual",
       reason: formatCompactionError(error),
     });
     return {
