SDK/Gateway: normalize or suppress raw chat events in run.events()

[BunsDev]

Live dogfood finding

During the live OpenMeow SDK dogfood run, run.events() returned a usable normalized stream, but it also emitted raw events whose underlying Gateway event was chat and whose payload looked like assistant delta content.

Evidence doc:

• https://github.com/OpenCoven/open-meow-sdk/blob/main/docs/live-dogfood-2026-04-29.md
• Commit: 916d755 (docs: add live dogfood findings)

Observed event sequence included:

run.started
assistant.delta
raw
assistant.delta
assistant.delta
assistant.delta
assistant.delta
assistant.delta
assistant.delta
run.completed

The raw event payload had raw.event: "chat" and assistant text fragments under message.content.

Impact

OpenMeow can render from assistant.delta, but app UIs need to either ignore/debug-log these raw events or risk duplicate assistant deltas.

Desired contract

For SDK-facing run.events():

• either normalize chat assistant delta payloads into stable assistant.delta / assistant.message events, or
• suppress duplicate raw chat deltas from the high-level run event stream and reserve them for rawEvents() / debug APIs.

Acceptance

• Live OpenMeow happy-path run has no raw/debug fallback for normal assistant text streaming.
• Raw provider/Gateway payloads remain available for debugging without being required for app UI rendering.

[BunsDev]

Upstream OpenClaw PR opened for this contract gap:

• fix(gateway): align sessions abort wait semantics openclaw/openclaw#74751
• Commit: bae93f5407 fix(sdk): align run event and cancel semantics

The PR suppresses Gateway chat projection snapshots from high-level SDK run.events() so OpenMeow can render from normalized assistant.delta / terminal events without duplicate raw chat fallback. rawEvents() remains available for debugging.

Fresh local verification before push:

• node scripts/run-vitest.mjs run --config test/vitest/vitest.unit.config.ts packages/sdk/src/index.test.ts → 12 passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.e2e.config.ts packages/sdk/src/index.e2e.test.ts → 3 passed
• pnpm --filter @openclaw/sdk build → build complete

Leaving this issue open until the upstream PR lands and OpenMeow can dogfood against the merged SDK/Gateway.

[BunsDev]

Dogfood update from 2026-05-02:

Validated the raw-event suppression/normalization concern in the live happy path.

Evidence:

• Live run event stream consumed through OpenMeow adapter and reducer.
• Observed only normalized run/assistant events:
  • run.started
  • assistant.delta
  • run.completed
• Raw event count in run.events() for the happy-path probe was 0.
• Fixture contract tests continue to assert known events render without falling back to debug/raw UI.

Assessment:

• Happy-path raw duplicate event leakage appears resolved.
• Recommend one final app-shell smoke test before closing.