Skip to content

refactor: add compact trim lifecycle seam#93695

Merged
jalehman merged 2 commits into
openclaw:mainfrom
jalehman:clawdbot-d02.1.9.1.34/31b-session-compact-lifecycle-seam
Jun 17, 2026
Merged

refactor: add compact trim lifecycle seam#93695
jalehman merged 2 commits into
openclaw:mainfrom
jalehman:clawdbot-d02.1.9.1.34/31b-session-compact-lifecycle-seam

Conversation

@jalehman

@jalehman jalehman commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What

Adds a storage-neutral accessor operation for manual sessions.compact transcript trimming. The gateway now calls one operation for transcript tail selection, .bak archive/rewrite, and stale token metadata cleanup.

Why

Path 3 needs SQLite to trim transcript rows and update session_entries.entry_json metadata in one backend transaction, rather than composing transcript artifact mutation and entry metadata writes in the gateway.

Changes

  • Add compact trim accessor seam
  • Route gateway manual trim
  • Preserve file-backed candidate order
  • Ratchet old trim composition
  • Cover success/no-op/missing cases

SQLite follow-up

The SQLite adapter should implement trimSessionTranscriptForManualCompact as one transaction: select/copy/delete transcript rows through the trim boundary and update entry JSON token/updated fields together. No SQLite schema or runtime storage flip is included here.

Testing

  • /Users/phaedrus/Projects/clawdbot/node_modules/.bin/oxfmt --check --threads=1 scripts/check-session-accessor-boundary.mjs test/scripts/check-session-accessor-boundary.test.ts src/config/sessions/session-accessor.ts src/config/sessions/session-accessor.test.ts src/gateway/server-methods/sessions.ts src/gateway/server.sessions.list-changed.test.ts
  • node scripts/run-vitest.mjs src/config/sessions/session-accessor.test.ts src/gateway/server.sessions.list-changed.test.ts test/scripts/check-session-accessor-boundary.test.ts
  • node scripts/check-session-accessor-boundary.mjs
  • git diff --check
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base upstream/main

Tracker: #88838

Real behavior proof

Behavior addressed: Manual sessions.compact with maxLines trims the selected session transcript through the accessor seam, archives the original transcript, and clears stale token/context metadata.

Real environment tested: Local live LaunchAgent gateway from clawdbot, built from PR head 1877d0f48e489ee6ec6a798f2d780eaf65c17112; pnpm openclaw --version reported OpenClaw 2026.6.8 (1877d0f). HTTP /healthz returned {"ok":true,"status":"live"}; HTTP /readyz returned {"ready":true,"failing":[]}; gateway status --json reported RPC ok: true and gateway version 2026.6.8.

Exact steps or command run after this patch:

git switch --detach 1877d0f48e489ee6ec6a798f2d780eaf65c17112
pnpm build
pnpm openclaw gateway restart
pnpm openclaw --version
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz
pnpm openclaw gateway status --json
pnpm openclaw gateway call health --json --timeout 5000
pnpm openclaw gateway call sessions.create --json --timeout 10000 --params '{"agentId":"main","label":"PR 93695 live proof"}'
# Seeded that returned session entry with four metadata JSONL transcript lines plus stale input/output/total token fields and contextBudgetStatus, then restarted so the live gateway loaded the seeded file-backed state.
pnpm openclaw gateway restart
pnpm openclaw gateway call sessions.compact --json --timeout 10000 --params '{"key":"agent:main:dashboard:911bdccc-ddc6-4350-8d0c-200bf2c35bf9","maxLines":2}'
# Verified the transcript file, archive file, and session store entry on disk.
pnpm openclaw gateway call sessions.delete --json --timeout 10000 --params '{"key":"agent:main:dashboard:911bdccc-ddc6-4350-8d0c-200bf2c35bf9"}'
# Removed proof-only archive/backup artifacts and verified no proof files remained.

Evidence after fix: sessions.compact returned ok: true, compacted: true, kept: 2, and archive 98ea11ca-b9f3-4d0b-a108-3683544b9a3c.jsonl.bak.2026-06-17T18-36-31.559Z for key agent:main:dashboard:911bdccc-ddc6-4350-8d0c-200bf2c35bf9. On disk, the active transcript contained only pr93695-created-line-3 and pr93695-created-line-4; the archive contained 4 original lines; the session store entry no longer had inputTokens, outputTokens, totalTokens, totalTokensFresh, or contextBudgetStatus; updatedAt changed to 1781721391567. Cleanup deleted the proof session and a final artifact scan returned leftovers: [].

Observed result after fix: The live gateway preserved the previous manual compact response shape while moving transcript tail selection, archive/rewrite, and stale token metadata cleanup behind the session accessor boundary.

What was not tested: Future SQLite adapter implementation, SQLite transactionality, doctor migration, SDK compatibility, broad CI completion after later main movement, and live gateway behavior on a post-1877d0f rebased head.

@openclaw-barnacle openclaw-barnacle Bot added gateway Gateway runtime scripts Repository scripts size: L maintainer Maintainer-authored PR labels Jun 16, 2026
@jalehman jalehman mentioned this pull request Jun 16, 2026
Closed
@jalehman jalehman self-assigned this Jun 17, 2026
@jalehman
jalehman force-pushed the clawdbot-d02.1.9.1.34/31b-session-compact-lifecycle-seam branch from 2f5c278 to 7504f0e Compare June 17, 2026 17:57
@jalehman
jalehman marked this pull request as ready for review June 17, 2026 17:57
@jalehman
jalehman force-pushed the clawdbot-d02.1.9.1.34/31b-session-compact-lifecycle-seam branch from 7504f0e to 1877d0f Compare June 17, 2026 18:01
@clawsweeper

clawsweeper Bot commented Jun 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 17, 2026, 4:11 PM ET / 20:11 UTC.

Summary
The PR adds trimSessionTranscriptForManualCompact, routes Gateway sessions.compact maxLines trimming through the session accessor, and adds focused behavior and boundary-guard tests.

PR surface: Source +230, Tests +192, Other +27. Total +449 across 6 files.

Reproducibility: not applicable. this is a planned internal refactor, not a bug report. Source comparison and the PR's focused tests cover the behavior-neutral manual trim path.

Review metrics: 1 noteworthy metric.

  • Internal storage seam: 1 added. The new accessor operation becomes a backend contract future SQLite storage must implement atomically before the storage flip.

Stored data model
Persistent data-model change detected: database schema: src/config/sessions/session-accessor.test.ts, serialized state: src/config/sessions/session-accessor.test.ts, serialized state: src/config/sessions/session-accessor.ts, serialized state: src/gateway/server-methods/sessions.ts, serialized state: src/gateway/server.sessions.list-changed.test.ts, unknown-data-model-change: src/config/sessions/session-accessor.test.ts, and 3 more. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: partial_overlap
Canonical: #88838
Summary: This PR is one slice of the broader session/transcript SQLite accessor migration tracked by the canonical issue; adjacent compact PRs touch different manual compaction behavior.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Maintainer session-state review should confirm the accessor operation is the intended Path 3 trim lifecycle boundary before merge.

Risk before merge

  • [P1] Manual compact rewrites active transcript artifacts and clears persisted token/context metadata; maintainers should confirm this is the intended transaction boundary for the Path 3 storage migration before merge.
  • [P1] The future SQLite adapter implementation is intentionally not included here, so the broader session/transcript migration remains tracked by Track core session/transcript SQLite migration via accessor seam #88838.

Maintainer options:

  1. Land after session-state review (recommended)
    If maintainers agree this is the intended storage-neutral trim boundary, merge after exact-head checks because no concrete code defect remains in this review.
  2. Hold for adapter contract clarification
    Pause the PR if maintainers want the SQLite transaction contract or active-run interaction spelled out more explicitly before accepting the seam.

Next step before merge

  • [P2] No narrow automated repair remains; the protected maintainer label and session-state storage contract need human review before merge.

Security
Cleared: No concrete security or supply-chain concern found; the diff does not change workflows, dependencies, lockfiles, secrets handling, permissions, or third-party code execution.

Review details

Best possible solution:

Land this as a focused Path 3 accessor-seam slice only after maintainer session-state review confirms the backend transaction contract and exact-head checks stay green.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a planned internal refactor, not a bug report. Source comparison and the PR's focused tests cover the behavior-neutral manual trim path.

Is this the best way to solve the issue?

Yes: moving tail selection, archive/rewrite, and stale token metadata cleanup behind session-accessor is the right owner boundary for this migration slice. The remaining decision is maintainer acceptance of the session-state transaction contract, not an automated code repair.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 5304a5b871ba.

Label changes

Label changes:

  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes live terminal proof for the manual compact path, including gateway health, sessions.compact output, transcript/archive verification, metadata cleanup, and cleanup of proof artifacts; the later commit is a mechanical type-narrowing/test-fixture repair with CI green.
  • remove rating: 🧂 unranked krab: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
  • remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

  • P2: This is a normal-priority internal session/transcript migration slice with limited immediate user-facing blast radius.
  • merge-risk: 🚨 session-state: The PR changes the manual compact path that archives/recreates transcript files and updates persisted session token/context metadata.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes live terminal proof for the manual compact path, including gateway health, sessions.compact output, transcript/archive verification, metadata cleanup, and cleanup of proof artifacts; the later commit is a mechanical type-narrowing/test-fixture repair with CI green.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes live terminal proof for the manual compact path, including gateway health, sessions.compact output, transcript/archive verification, metadata cleanup, and cleanup of proof artifacts; the later commit is a mechanical type-narrowing/test-fixture repair with CI green.
Evidence reviewed

PR surface:

Source +230, Tests +192, Other +27. Total +449 across 6 files.

View PR surface stats
Area Files Added Removed Net
Source 2 291 61 +230
Tests 3 192 0 +192
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 1 27 0 +27
Total 6 510 61 +449

What I checked:

  • Repository policy read and applied: Root and scoped AGENTS guidance require whole-path session-state review and treat persisted session/transcript changes as merge-risk-sensitive. (AGENTS.md:1, 5304a5b871ba)
  • Current main still lacks the new seam: A current-main grep for trimSessionTranscriptForManualCompact returned no matches, so this PR is still the active implementation candidate for this slice. (src/config/sessions/session-accessor.ts, 5304a5b871ba)
  • Current main manual trim composition: Current main reads tail transcript lines in the gateway, archives the JSONL file, rewrites the tail, and then clears stale token/context metadata directly in the session store. (src/gateway/server-methods/sessions.ts:2620, 5304a5b871ba)
  • PR accessor implementation: The PR head moves transcript target resolution, bounded tail streaming, archive/rewrite, and stale token/context metadata cleanup into trimSessionTranscriptForManualCompact. (src/config/sessions/session-accessor.ts:693, 425212a1ec68)
  • PR gateway routing: The gateway maxLines branch now delegates to the accessor operation and preserves compacted, no-op, and no-transcript response shapes. (src/gateway/server-methods/sessions.ts:2619, 425212a1ec68)
  • Behavior and guard coverage: The PR adds accessor tests for trim/archive/metadata cleanup and stale generated sessionFile ordering, plus gateway tests for selected/default agent, no-op, and no-transcript maxLines responses. (src/config/sessions/session-accessor.test.ts:547, 425212a1ec68)

Likely related people:

  • jalehman: Authored/merged the initial session accessor seam and recent session patch/reset lifecycle seam work that this trim lifecycle slice extends. (role: feature owner and recent area contributor; confidence: high; commits: ef47dd610c87, c85bd452846b, c41bc58cf612; files: src/config/sessions/session-accessor.ts, src/gateway/server-methods/sessions.ts, scripts/check-session-accessor-boundary.mjs)
  • amknight: Opened the adjacent manual compaction PR that changes forced manual compaction behavior in agent-core, which shares the manual compact lifecycle surface but not this storage seam. (role: adjacent manual-compaction contributor; confidence: medium; commits: 3aecc4ee9d1f, fd09d2e7d0cb; files: packages/agent-core/src/harness/compaction/compaction.ts, src/agents/sessions/agent-session.ts)
  • Alix-007: Opened the adjacent sessions compact CLI PR that also touches the Gateway maxLines compact path and active-run guard behavior. (role: adjacent compact CLI/gateway contributor; confidence: medium; files: src/gateway/server-methods/sessions.ts, src/commands/sessions-compact.test.ts, docs/cli/sessions.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jun 17, 2026
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jun 17, 2026
@jalehman
jalehman merged commit e442b57 into openclaw:main Jun 17, 2026
185 of 191 checks passed
@jalehman
jalehman deleted the clawdbot-d02.1.9.1.34/31b-session-compact-lifecycle-seam branch June 17, 2026 21:29
@github-actions github-actions Bot mentioned this pull request Jun 17, 2026
Open
crh-code pushed a commit to crh-code/openclaw that referenced this pull request Jun 18, 2026
@jalehman @crh-code
refactor: add compact trim lifecycle seam (openclaw#93695)
4986625 
* clawdbot-d02.1.9.1.32: add compact trim lifecycle seam

* fix: repair session compact type narrowing
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 18, 2026
@jalehman
refactor: add compact trim lifecycle seam (openclaw#93695)
bb5dd2f 
* clawdbot-d02.1.9.1.32: add compact trim lifecycle seam

* fix: repair session compact type narrowing
This was referenced Jun 19, 2026
Merged
Merged
Closed
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@jalehman jalehman

Labels

gateway Gateway runtime maintainer Maintainer-authored PR merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. scripts Repository scripts size: L status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jalehman