PR #78619: fix(compaction): ignore transcript metadata bytes for token pressure

• Repository: openclaw/openclaw
• Author: hera8939
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78619

Description (problem / solution / changelog)

Summary

• Problem: stale preflight compaction checks could count whole transcript JSONL byte size as token pressure, including session headers, custom records, and plugin metadata that are not active model context.
• Why it matters: metadata-heavy sessions could compact every few minutes even when the active context was small and the transcript file was below maxActiveTranscriptBytes, disrupting conversations and wasting model calls.
• What changed: stale token estimation now prefers latest usage, active-message estimates, and only bytes appended after the latest usage entry; it no longer treats whole raw transcript size as token pressure.
• What did NOT change (scope boundary): explicit maxActiveTranscriptBytes byte-guard behavior, compaction execution, transcript rotation, memory plugin behavior, provider/model settings, and channel routing are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78604
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: metadata-heavy transcripts should not trigger token-based preflight compaction when active model context is below the threshold and the file is below maxActiveTranscriptBytes.
• Real environment tested: local OpenClaw checkout on Linux using the production runPreflightCompactionIfNeeded path against a temp OpenClaw session store and transcript.
• Exact steps or command run after this patch: ran a temp-session OpenClaw preflight script with pnpm exec tsx, using truncateAfterCompaction: true, maxActiveTranscriptBytes: "10mb", stale totalTokensFresh: false, a 450KB custom transcript payload, and MiniMax model/session metadata.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

openclaw_preflight_compaction_real_setup=ok
session_file_bytes=450198
max_active_transcript_bytes=10485760
token_state_fresh=false
returned_same_entry=true
preflight_compaction_phase_seen=false
compaction_count=0

• Observed result after fix: OpenClaw returned the same active session entry, did not enter the preflight_compacting phase, and did not increment compaction count.
• What was not tested: live MiniMax + Feishu WebSocket + memory-lancedb-pro deployment.
• Before evidence (optional but encouraged): issue #78604 reports OpenClaw 2026.5.6 compacting five times between 03:11:18 and 03:33:28 UTC+8 while the transcript was about 666KB, below a 10MB byte guard.

Root Cause (if applicable)

• Root cause: the stale preflight token fallback mixed two different signals: model-context token pressure and raw JSONL transcript file size. Whole-file byteSize / 4 could overestimate token pressure because JSONL contains non-context records such as session headers, custom entries, and plugin metadata.
• Missing detection / guardrail: no regression covered stale token state with a metadata-heavy transcript whose active model context remained small.
• Contributing context (if known): maxActiveTranscriptBytes is the explicit transcript-size guard. The token path should not implicitly recreate that byte guard by using whole-file bytes as context tokens.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/auto-reply/reply/agent-runner-memory.test.ts
• Scenario the test should lock in: stale totalTokensFresh: false, 450KB custom metadata payload, small assistant usage, transcript rotation enabled, and maxActiveTranscriptBytes: "10mb" should not trigger preflight compaction.
• Why this is the smallest reliable guardrail: the bug is in preflight token estimation, so the focused runner-memory test proves the decision without requiring a live provider/channel/plugin setup.
• Existing test that already covers this (if any): existing tests covered stale usage and content appended after latest usage, but not non-context metadata bytes.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Metadata-heavy sessions should no longer compact every few minutes when active model context is not actually near the token threshold.

Diagram (if applicable)

Before:
stale token state -> whole transcript bytes / 4 -> false token pressure -> repeated compaction

After:
stale token state -> latest usage + active messages + trailing post-usage bytes -> real token pressure decision

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: local Node/pnpm checkout
• Model/provider: MiniMax metadata in local temp-session proof; no live model call required
• Integration/channel (if any): preflight compaction/session memory path
• Relevant config (redacted): truncateAfterCompaction: true, maxActiveTranscriptBytes: "10mb"

Steps

1. Create a temp OpenClaw session transcript with a large custom metadata record and small assistant usage.
2. Mark the session entry token state stale with totalTokensFresh: false.
3. Run the production preflight compaction path with transcript rotation and 10MB byte guard enabled.

Expected

• Preflight token compaction does not run because active model context is below threshold and the transcript is below the explicit byte guard.

Actual

• Before this patch, whole raw transcript bytes could contribute to token pressure and trigger compaction.
• After this patch, copied live output shows preflight_compaction_phase_seen=false and compaction_count=0.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Supplemental checks run:

• pnpm test src/auto-reply/reply/agent-runner-memory.test.ts
• pnpm exec oxfmt --check --threads=1 src/auto-reply/reply/agent-runner-memory.ts src/auto-reply/reply/agent-runner-memory.test.ts CHANGELOG.md
• pnpm changed:lanes --json
• pnpm check:changed
• git diff --check

Human Verification (required)

• Verified scenarios: local production-path preflight run against a temp OpenClaw session store/transcript, focused metadata-heavy stale-token regression, existing conservative post-usage content behavior, formatting, changed-lane type/lint/guards.
• Edge cases checked: bytes appended after latest usage still count conservatively through trailing-byte accounting.
• What you did not verify: live MiniMax/Feishu/memory-lancedb-pro deployment.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: underestimating token pressure when usage is stale and transcript content after the latest usage is large.
  • Mitigation: the estimator still includes active-message token estimates and trailing bytes after the latest usage entry.

## Changed files

- `CHANGELOG.md` (modified, +1/-0)
- `src/auto-reply/reply/agent-runner-memory.test.ts` (modified, +128/-0)
- `src/auto-reply/reply/agent-runner-memory.ts` (modified, +50/-27)