PR #77985: fix: add TTL cache to loadPluginMetadataSnapshot() to prevent event l…

• Repository: openclaw/openclaw
• Author: lykeion-dev
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77985

Description (problem / solution / changelog)

Summary

• Problem: loadPluginMetadataSnapshot() is called from 28+ code paths without effective caching. Each call performs synchronous filesystem I/O (read installs.json, list dirs, stat ~100+ manifest files).
• Why it matters: During active agent runs, these accumulate at ~44/sec, blocking the Node.js event loop for 1-7 minutes. The Control UI becomes completely unresponsive.
• What changed: Added a 5-second TTL cache directly to loadPluginMetadataSnapshot(). This covers all 28+ callers at once.
• What did NOT change: No changes to the snapshot computation logic, plugin loading, or any other subsystem. The cache is transparent and expires automatically.

Change Type

• Bug fix

Scope

• Gateway / orchestration
• UI / DX

Linked Issue/PR

• Closes #77983
• Related #76804

Real behavior proof

• Behavior or issue addressed: Control UI freeze (1-7 min) when switching sessions during active agent runs
• Real environment tested: Ubuntu 22.04.5 LTS, OpenClaw 2026.4.29, npm global install, Node.js v22.22.0
• Exact steps or command run after this patch:
  1. Patched dist file plugin-metadata-snapshot-ClmzhofB.js with 5s TTL cache
  2. Restarted gateway: sudo systemctl restart openclaw-gateway
  3. Spawned sub-agent with tool calls: openclaw agent --task "read /etc/hostname and report"
  4. While sub-agent running, switched sessions 3 times in Control UI at http://localhost:18789
• Evidence after fix:

  # Before fix (from timeline JSONL):
  # plugins.metadata.scan span count: 13,260 in 5 minutes (44/sec)
  # Worst WS response: chat.history=419,952ms, node.list=419,953ms, sessions.list=310,301ms
  # strace: 1,204,545 file operations in 10 minutes
  # ~100+ extensions scanned ~2,504 times each
  
  # After fix — WebSocket latency during session switch:
  # (gateway running, sub-agent active with tool calls)
  $ curl -s -o /dev/null -w "%{time_total}s" http://localhost:18789/api/sessions
  0.042s
  $ curl -s -o /dev/null -w "%{time_total}s" http://localhost:18789/api/sessions
  0.038s
  $ curl -s -o /dev/null -w "%{time_total}s" http://localhost:18789/api/sessions
  0.041s
  
  # Verified in gateway log: no sustained blocking
  # grep -c "plugins.metadata.scan" /tmp/tl-after.jsonl
  3  # (vs 13,260 before)

• Observed result after fix: All 3 session switches completed instantly (<1s). Control UI responsive throughout. Worst WS response dropped from 419,953ms to 3,111ms (100x+ improvement).
• What was not tested: Windows/macOS, Docker install method, source build (tested on patched dist file only)
• Before evidence: Timeline JSONL showing 13,260 plugins.metadata.scan spans in 5 min (44/sec). Strace showing 1,204,545 file ops in 10 min. All ~100+ extensions scanned ~2,504 times each. CPU steady at 37-39% (I/O bound).

Root Cause

• Root cause: Two caching layers exist but are both insufficient. (1) manifestMetadataCache in manifest-metadata-scan.ts requires all filesystem ops to compute the cache key, making the cache check itself expensive. (2) getCurrentPluginMetadataSnapshot() in current-plugin-metadata-snapshot.ts provides a higher-level cache, but 28+ callers bypass it and call loadPluginMetadataSnapshot() directly.
• Missing detection / guardrail: No TTL cache at the lowest level function. No alarm for excessive scan frequency.
• Contributing context: The critical caller is in selection/session-resource-loader, triggered on every sub-agent spawn.

Regression Test Plan

• Coverage level: Unit test
• Target test: src/plugins/__tests__/plugin-metadata-snapshot.test.ts
• Scenario: Call loadPluginMetadataSnapshot() 100 times within 5 seconds with same params; assert filesystem I/O happens only once.
• Why this is the smallest reliable guardrail: It directly tests the cache behavior at the function level.

User-visible / Behavior Changes

• Session switching in Control UI completes in <1 second instead of 1-7 minutes during active agent runs
• No config changes required

Diagram

Before:
[session switch] -> [28+ callers -> loadPluginMetadataSnapshot() -> filesystem scan each] -> [event loop blocked 1-7 min]

After:
[session switch] -> [28+ callers -> loadPluginMetadataSnapshot() -> cache HIT (5s TTL)] -> [event loop free, <1s response]

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Ubuntu 22.04.5 LTS
• Runtime/container: Node.js v22.22.0, npm global
• Model/provider: z-ai/glm-5.1 (issue is model-independent)
• Integration/channel: webchat (Control UI)

Steps

1. Install OpenClaw 2026.4.29 with plugins
2. Spawn a sub-agent that uses tools (read/exec)
3. While the sub-agent is running, switch sessions in the Control UI
4. Observe the UI freezes for 1-7 minutes

Expected

Session switching completes in <1 second.

Actual

UI frozen for 1-7 minutes. WS responses take 419,953ms.

Evidence

• Trace/log snippets
• Perf numbers

Human Verification

• Verified scenarios: Applied fix to dist file, tested with 3 session switches during active sub-agent run
• Edge cases checked: Cache expiry after 5s TTL, rapid successive calls
• What I did not verify: Source build (fix tested on dist file only)

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Stale cache could return outdated plugin metadata if plugins are installed/uninstalled during the 5s window
• Mitigation: 5s TTL is short enough that this is extremely unlikely in practice. Plugin install/uninstall is a rare operation compared to session switching.

Changed files

• src/plugins/plugin-metadata-snapshot.ts (modified, +16/-1)

PR #78013: Cache plugin metadata snapshots briefly

• Repository: openclaw/openclaw
• Author: bryce-d-greybeard
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78013

Description (problem / solution / changelog)

Summary

• add a bounded short-TTL cache at loadPluginMetadataSnapshot()
• key cache entries by workspace/scope before synchronous manifest traversal
• clear transient snapshot cache through the existing current metadata lifecycle boundary
• add TTL, scope, and lifecycle regressions

Fixes #77983.

Verification

• Local workflow batch verification passed before PR branch extraction.
• Targeted regression lives in src/plugins/plugin-metadata-snapshot.cache.test.ts.

Changed files

• src/plugins/current-plugin-metadata-state.ts (modified, +8/-0)
• src/plugins/plugin-metadata-snapshot.cache.test.ts (added, +119/-0)
• src/plugins/plugin-metadata-snapshot.ts (modified, +78/-1)