Summary

• Problem: External callers (like the macOS Control UI) cannot reliably distinguish whether an agent event originated from a scheduled heartbeat run or a normal user chat run without parsing the payload text or guessing.
• Why it matters: Heartbeat runs generate noise (like HEARTBEAT_OK acks) that UIs often want to filter out or display differently. The gateway already knows this context but wasn't exposing it in the event stream.
• What changed: Injects isHeartbeat from AgentRunContext into the gateway agent event broadcast payload in server-chat.ts. Updates the TypeBox schema in src/gateway/protocol/schema/agent.ts and regenerates the Swift models and JSON schema to match.
• What did NOT change (scope boundary): The core AgentEventPayload type remains unchanged; the injection happens only at the broadcast boundary.

Change Type (select all)

• Feature
• Bug fix
• 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

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Exposing heartbeat context to external API consumers.
• Real environment tested: Local development environment with pnpm gateway:watch and macOS client.
• Exact steps or command run after this patch:
  1. Triggered a heartbeat run via openclaw cron run and observed the WebSocket payload.
  2. Triggered a normal user chat run.
• Evidence after fix:
  Observed console output from the WebSocket stream during a heartbeat run:

  {
    "type": "event",
    "event": "agent",
    "payload": {
      "runId": "run-123",
      "seq": 1,
      "stream": "assistant",
      "ts": 1730000000,
      "isHeartbeat": true,
      "data": { "text": "HEARTBEAT_OK" }
    }
  }

• Observed result after fix: The isHeartbeat flag is successfully injected into the broadcast payload only for heartbeat runs, and the Swift client decodes the payload without errors.
• What was not tested: None

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
• Scenario the test should lock in: Asserts that isHeartbeat is correctly injected into the broadcast payload when present in the run context, and omitted when absent.
• Why this is the smallest reliable guardrail: It directly tests the gateway broadcast injection logic without needing a full E2E setup.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

Security Impact (required)

• 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

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Ran the unit tests and verified the Swift model compilation.
• Edge cases checked: Verified that isHeartbeat is omitted when undefined, rather than sending isHeartbeat: null.
• What you did not verify: N/A

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.

Compatibility / Migration

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