Summary

• Problem: High-volume Gateway agent text events could fan out too frequently while a run was streaming, and the throttle path could drop an intermediate buffered delta when a later post-window delta arrived.
• Why it matters: Streaming clients should receive fewer redundant events without losing assistant or thinking text bytes.
• What changed: Added stream-specific Gateway agent-event throttling, cumulative text-delta buffering, lifecycle-safe first text emission, and cleanup for the new throttle state.
• Follow-up fix: Flush pending assistant/thinking agent deltas before sending a post-window delta, and wire the real chat.abort request path to clear agent throttle buffers.
• What did NOT change: No protocol shape change, no UI behavior change, no plugin/channel-specific policy, and no live model/provider configuration change.

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

• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

External contributors must show after-fix evidence from a real OpenClaw setup. Unit tests, mocks, lint, typechecks, snapshots, and CI are supplemental only. Screenshots are encouraged even for CLI, console, text, or log changes; terminal screenshots and copied live output count. Be mindful of private information like IP addresses, API keys, phone numbers, non-public endpoints, or other private details when providing evidence.

• Behavior or issue addressed: Gateway WebSocket agent-event fanout for assistant text streams must throttle bursts without dropping the buffered middle delta when a later post-window delta arrives.
• Real environment tested: Local isolated OpenClaw Gateway WebSocket server from this worktree, started with loopback binding, external channels/providers skipped, and a real GatewayClient connected as an auto-approved operator device with operator.read, operator.write, and operator.admin scopes.
• Exact steps or command run after this patch:
  1. Ran pnpm exec tsx - with a temporary proof script that starts startGatewayServer, connects GatewayClient, registers sessionKey: "main", emits assistant deltas Hel, lo, and ! with 50ms/170ms timing around the 150ms throttle window, and asserts the WebSocket client receives all three deltas in order.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Copied live console output from the Gateway proof script.

  REAL_BEHAVIOR_PROOF agent event throttle
  gateway=ws://127.0.0.1:56626
  authScopes=["operator.admin","operator.read","operator.write"]
  runId=proof-run-fb786c05-5cff-46c4-bb83-873f4ba2b492
  observedAssistantDeltas=["Hel","lo","!"]
  observedAssistantSeqs=[1,2,3]
  result=middle delta delivered before post-window delta; no assistant text loss
  

• Observed result after fix: The real Gateway WebSocket client received the buffered middle assistant delta (lo) before the later post-window delta (!), preserving assistant text order and content across the throttle boundary.
• What was not tested: External provider credentials, external channel delivery, and UI screenshots; the changed surface is server-side Gateway event fanout and abort cleanup.
• Before evidence (optional but encouraged): The previous implementation deleted the buffered assistant delta when the next post-window delta arrived, so a Hel / lo / ! burst could be observed as Hel / !.

Root Cause (if applicable)

• Root cause: The throttle state originally treated buffered text as replaceable latest-state, so the next post-window text event deleted the pending buffered delta instead of flushing it first. The direct chat.abort request path also did not receive the new agent throttle maps, so it could not clear stale assistant/thinking throttle state.
• Missing detection / guardrail: Gateway event tests covered burst coalescing but did not assert the boundary case where an in-window buffered delta is followed by a post-window delta.
• Contributing context (if known): The event path mixes lifecycle and text payloads under the same agent event channel, so throttle state needs to distinguish stream family from run lifecycle and be cleaned through every run-abort path.

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/gateway/server-chat.agent-events.test.ts, src/gateway/server-methods/chat.abort-authorization.test.ts, src/gateway/chat-abort.test.ts, src/gateway/server-maintenance.test.ts, src/gateway/server-startup-early.test.ts, src/gateway/server-request-context.test.ts
• Scenario the test should lock in: High-frequency assistant/thinking text bursts are coalesced with cumulative deltas, buffered deltas are flushed before post-window deltas, lifecycle/start does not seed the text throttle window, and abort/maintenance cleanup removes stream-specific throttle state.
• Why this is the smallest reliable guardrail: The affected behavior is the Gateway server event fanout path and its internal throttle state; focused Gateway tests exercise that path without requiring provider credentials or a live model.
• Existing test that already covers this (if any): Existing burst coverage existed but was not specific enough for the post-window buffered-delta flush and real abort wiring.
• If no new test is added, why not: N/A, new coverage is included.

User-visible / Behavior Changes

Gateway clients may receive fewer redundant high-frequency assistant/thinking text agent events during streaming bursts, while receiving the same cumulative text content after throttled flushes.

Diagram (if applicable)

Before:
[agent text burst] -> [stream throttle] -> [drop pending buffered delta on post-window send]

After:
[agent text burst] -> [stream throttle] -> [flush pending buffered delta before post-window send]

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: macOS local development worktree
• Runtime/container: Node 22+ with repo pnpm scripts
• Model/provider: N/A; the real proof uses Gateway WebSocket agent-event fanout directly and does not require provider credentials
• Integration/channel (if any): Gateway server event fanout
• Relevant config (redacted): Isolated loopback Gateway state; external channels/providers skipped

Steps

1. Run the real Gateway WebSocket proof script described above.
2. Run focused Gateway event, abort, maintenance, startup, and request-context tests.
3. Run changed-code checks, format validation, and diff validation.

Expected

• Assistant/thinking text bursts are throttled without losing intermediate deltas.
• Lifecycle/start events do not consume the text throttle window.
• Abort and maintenance cleanup remove stream-specific throttle entries.

Actual

• Real Gateway WebSocket proof observed assistant deltas ["Hel","lo","!"] with seqs [1,2,3].
• Focused Gateway tests passed: Test Files 6 passed (6), Tests 85 passed (85).
• pnpm check:changed, pnpm check:changed --staged, pnpm format:check -- <changed gateway files>, and git diff --check passed locally.

Evidence

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

Human Verification (required)

• Verified scenarios: Real Gateway WebSocket assistant delta fanout, cumulative assistant text delta buffering, thinking stream coalescing, lifecycle/start first-text behavior, media/replace non-coalescing behavior, abort cleanup, and maintenance cleanup.
• Edge cases checked: Stream-specific throttle keys for assistant and thinking text, non-text lifecycle events, media payloads, replace payloads, and completed-run cleanup.
• What you did not verify: External provider credentials, external channel delivery, and UI screenshots.
• AI-assisted: Yes, Codex assisted with implementation and review.

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: Event timing changes can hide regressions if future Gateway event payloads are incorrectly classified as coalescible text.
  • Mitigation: Coalescing is limited to assistant/thinking text deltas, excludes media and replace payloads, and is covered by focused Gateway tests.