Skip to content

Run context-engine turn maintenance as idle-aware background work#65233

Merged
jalehman merged 11 commits into
openclaw:mainfrom
electricsheephq:codex/background-turn-maintenance
Apr 13, 2026
Merged

Run context-engine turn maintenance as idle-aware background work#65233
jalehman merged 11 commits into
openclaw:mainfrom
electricsheephq:codex/background-turn-maintenance

Conversation

@100yenadmin

Copy link
Copy Markdown
Contributor

Summary

Closes #65220.

This teaches context engines to opt into background turn maintenance and moves turn-triggered maintenance off the foreground session lane when turnMaintenanceMode === "background". For lossless-claw, that means proactive post-turn maintenance can be queued as a hidden task instead of blocking the next user turn.

Why

  • Today the host awaits both afterTurn() and maintain(... reason: "turn") inline on the session path.
  • Even if a plugin removes heavy foreground work, the host still controls whether turn maintenance blocks the lane.
  • The result is visible assistant output followed by dead time before the next command can start.
  • Subagent completion announce traffic can time out behind a stalled main lane.

What Changed

  • Added turnMaintenanceMode?: "foreground" | "background" to context-engine info.
  • Added allowDeferredCompactionExecution?: boolean to runtime context.
  • When a context engine opts into background mode, runContextEngineMaintenance(... reason: "turn") now:
    • queues one hidden maintenance task per session key
    • coalesces repeated requests
    • waits for the session lane to go idle before executing
    • runs maintenance with allowDeferredCompactionExecution: true
    • uses task delivery/status infrastructure instead of a visible subagent or announce flow
  • Long-running or failed deferred maintenance can surface subtle task updates to the session.
  • Fast deferred maintenance stays silent.

Guarantees

  • Proactive turn maintenance no longer blocks the immediate next foreground turn for engines that opt in.
  • Overflow/timeout/manual compaction remains synchronous in the plugin/runtime paths that require correctness.
  • Hidden maintenance is not a child agent run and does not create synthetic subagent sessions.

Validation

  • pnpm test -- --run src/agents/pi-embedded-runner/context-engine-maintenance.test.ts src/infra/backoff.test.ts passed
  • NODE_OPTIONS=--max-old-space-size=8192 pnpm exec tsc -p tsconfig.json --noEmit still reports preexisting unrelated AbortSignal type errors in unchanged extensions/telegram/src/bot.ts

Companion Plugin Work

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation size: XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Turn-triggered context-engine maintenance is awaited inline and can stall the session lane

3 participants