feat(core): add coalesced harness display-state subscriptions

[mbenhamd]

Adds Harness.subscribeDisplayState() for UI, SSE, TUI, and bridge consumers that render from HarnessDisplayState. Raw subscribe() still delivers every event for logs, debugging, analytics, and replay.

Example usage:

render(harness.getDisplayState());

const unsubscribe = harness.subscribeDisplayState(render, {
  windowMs: 250,
  maxWaitMs: 500,
});

The scheduler coalesces high-frequency message and tool updates, emits fresh display-state snapshots, and flushes critical lifecycle updates immediately.

Fixes #15973.

Validated with pnpm --filter ./packages/core test -- display-state, pnpm --filter ./packages/core check, and pnpm build:core.

ELI5

This PR adds a smarter way for UI components to listen to harness updates. Instead of getting bombarded with every single internal event, they can now use subscribeDisplayState() to receive batched updates that combine rapid changes into fewer snapshots, while keeping the old raw subscribe() method unchanged for debugging and logging.

Overview

This PR introduces Harness.subscribeDisplayState(), a new UI-facing subscription API that delivers coalesced HarnessDisplayState snapshots. It implements intelligent batching of high-frequency internal events (messages, tool updates) into consolidated display-state snapshots, while preserving the raw event semantics of the existing subscribe() API. Critical lifecycle events (agent start/end, errors, approvals, suspensions, questions, plans) bypass coalescing and flush immediately.

Key Changes

New Display State Scheduler Module

• display-state-scheduler.ts: Introduces DisplayStateScheduler class that buffers non-critical display state updates and dispatches them using two configurable timers:
  • windowMs (default 250ms): throttle window that resets on each non-critical update
  • maxWaitMs (default 500ms): maximum wait time to prevent starvation
  • Critical updates bypass buffering and flush immediately
  • Deep-clones entire HarnessDisplayState before invoking listeners to ensure isolation
  • Catches and logs listener errors via console.error without disrupting other listeners
  • Exports constants: DEFAULT_DISPLAY_STATE_SUBSCRIPTION_OPTIONS and CRITICAL_DISPLAY_STATE_EVENT_TYPES

API Additions to Harness

• getDisplayState(): Returns a snapshot of current HarnessDisplayState for initial rendering
• subscribeDisplayState(listener, options?): Registers a coalesced display-state listener that returns an unsubscribe function
  • Accepts optional windowMs and maxWaitMs tuning parameters
  • Listener is not invoked immediately (caller must use getDisplayState() for initial render)
  • All subscriptions are cleaned up during harness.destroy()

Integration Updates

• Modified Harness.emit() to notify schedulers after dispatching events, passing isCritical flag based on event type
• Event type display_state_changed is skipped to avoid double-notification
• Harness destroy method extended to dispose and clear all registered schedulers

Type System Enhancements

• New types in types.ts:
  • HarnessDisplayStateListener: callback type receiving HarnessDisplayState, may be sync or async
  • HarnessDisplayStateSubscriptionOptions: configuration interface for windowMs and maxWaitMs
• Index re-exports: Both new types exported from harness module

Documentation

• Updated harness-class.mdx with comprehensive documentation of both new APIs
• Clarified that subscribe() is intended for raw event logs while subscribeDisplayState() is preferred for UI rendering
• Added changeset documenting the new API with usage examples

Testing

Comprehensive test suite in display-state.test.ts covering:

• Coalescing behavior driven by windowMs with fake timers
• Forced flushes at maxWaitMs to prevent starvation
• Critical event types trigger immediate (non-coalesced) emission
• Emitted snapshots are fresh deep-clones isolated from harness internal state
• Unsubscribe and harness.destroy() properly cancel pending timer flushes
• Custom coalescing options change flush timing as configured
• Raw subscriptions continue to receive every event while display subscribers remain coalesced
• Listener errors are caught and logged without preventing other listeners
• Validation of key snapshot fields like isRunning, pendingApproval, pendingSuspension, etc.

Validation

Changes have been validated with:

• pnpm --filter ./packages/core test -- display-state
• pnpm --filter ./packages/core check
• pnpm build:core

Fixes issue #15973.

[changeset-bot]

🦋 Changeset detected

Latest commit: 1038e35

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@mastra/core	Patch
mastracode	Patch
@mastra/mcp-docs-server	Patch
@internal/playground	Patch
@mastra/client-js	Patch
@mastra/opencode	Patch
@mastra/longmemeval	Patch
mastra	Patch
@mastra/deployer-cloud	Patch
@mastra/deployer-vercel	Patch
@mastra/playground-ui	Patch
@mastra/react	Patch
@mastra/server	Patch
@mastra/deployer	Patch
create-mastra	Patch
@mastra/express	Patch
@mastra/fastify	Patch
@mastra/hono	Patch
@mastra/koa	Patch
@mastra/deployer-cloudflare	Patch
@mastra/deployer-netlify	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@mbenhamd is attempting to deploy a commit to the Mastra Team on Vercel.

A member of the Team first needs to authorize it.

[dane-ai-mastra]

Thank you for your contribution!

Please ensure that your PR fixes an existing issue and that you have linked it in the description (e.g. with Fixes #1234).

We use CodeRabbit for automated code reviews. Please address all feedback from CodeRabbit by either making changes to your PR or leaving a comment explaining why you disagree with the feedback. Since CodeRabbit is an AI, it may occasionally provide incorrect feedback.

Addressing CodeRabbit's feedback will greatly increase the chances of your PR being merged. We appreciate your understanding and cooperation in helping us maintain high code quality standards.

Comment @coderabbitai review in case you want to trigger a review.

[coderabbitai]

Walkthrough

Introduces a new subscribeDisplayState() API to the Harness class that provides coalesced display-state snapshots to UI consumers. The implementation includes a scheduler that buffers non-critical updates using configurable timing windows, flushes critical events immediately, deep-clones snapshots before delivery, and includes comprehensive test coverage validating coalescing behavior, cleanup, and isolation guarantees.

Changes

Cohort / File(s)	Summary
Documentation & Changeset .changeset/five-hands-punch.md, docs/src/content/en/reference/harness/harness-class.mdx	Documents new getDisplayState() snapshot method and subscribeDisplayState(listener, options?) API with configurable windowMs and maxWaitMs for coalesced delivery. Clarifies that subscribe() remains for raw event logs while subscribeDisplayState() targets UI rendering paths.
Type Definitions packages/core/src/harness/types.ts, packages/core/src/harness/index.ts	Adds HarnessDisplayStateListener callback type and HarnessDisplayStateSubscriptionOptions configuration interface with optional windowMs and maxWaitMs properties. Exports new types from harness module.
Display State Scheduler packages/core/src/harness/display-state-scheduler.ts	Implements DisplayStateScheduler class that buffers non-critical updates with throttling and max-wait timers, flushes critical events immediately, deep-clones entire state before listener invocation, prevents post-disposal operations, and logs listener errors without blocking other subscribers.
Harness Integration packages/core/src/harness/harness.ts	Adds subscribeDisplayState() method that instantiates scheduler instances with configurable options and defaults. Extends emit() to notify active schedulers after dispatching events, marking certain event types as critical for immediate flush. Extends destroy() to dispose and clear all registered schedulers.
Test Suite packages/core/src/harness/display-state.test.ts	Comprehensive Vitest suite using fake timers validating coalesced emission behavior driven by windowMs and maxWaitMs, critical event immediate flushing, snapshot freshness and deep isolation, unsubscribe/destroy cleanup, custom timing options, raw subscription compatibility, and listener error handling without blocking other subscribers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~35 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title is concise, descriptive, uses imperative mood with proper capitalization, and directly summarizes the main feature addition.
Linked Issues check	✅ Passed	All coding objectives from issue #15973 are met: subscribeDisplayState() API added with coalescing logic, critical events flush immediately, tests cover coalescing/max-wait/cleanup/compatibility, and validation commands passed.
Out of Scope Changes check	✅ Passed	All changes are directly related to the coalesced display-state subscription feature; no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/core/src/harness/display-state-scheduler.ts`:
- Around line 29-77: The cloneDisplayState function currently shallow-copies
nested opaque payloads and Date objects which can leak mutations (e.g., fields
named args, result, suspendPayload and any Date properties); update
cloneDisplayState to deep-clone those unknown payloads and Date instances when
copying structures like activeSubagents.toolCalls, modifiedFiles.operations (and
any tool call payloads), tasks/previousTasks items, and any payloads on
pendingApproval/pendingSuspension/pendingQuestion so that objects/arrays are
recursively cloned and Date objects are copied via new Date(date.getTime()) (or
JSON-safe deep clone for plain payloads) to eliminate shared references between
snapshots and live state.

In `@packages/core/src/harness/harness.ts`:
- Around line 2570-2585: The subscribeDisplayState method registers a
DisplayStateScheduler into this.displayStateSchedulers but destroy() does not
clean them up; update the Harness.destroy (or equivalent teardown) to iterate
over this.displayStateSchedulers, call scheduler.dispose() for each
DisplayStateScheduler instance and then clear the Set
(this.displayStateSchedulers.clear()) to stop timers and prevent callbacks after
teardown; keep subscribeDisplayState’s current unsubscribe behavior (deleting
and disposing the single scheduler) intact so explicit unsubscribes still work.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 56d115e3-1b1a-44ef-9df9-f7d43f80a834

📥 Commits

Reviewing files that changed from the base of the PR and between 1a55145 and 3604a3a.

📒 Files selected for processing (10)

• .changeset/brown-lamps-lie.md
• .changeset/five-hands-punch.md
• docs/src/content/en/reference/harness/harness-class.mdx
• packages/core/src/harness/display-state-scheduler.ts
• packages/core/src/harness/display-state.test.ts
• packages/core/src/harness/harness.ts
• packages/core/src/harness/index.ts
• packages/core/src/harness/types.ts
• stores/convex/src/server/storage.test.ts
• stores/convex/src/server/storage.ts

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/core/src/harness/display-state.test.ts (1)

1275-1341: ⚡ Quick win

Cover the full critical-event contract in this suite.

These assertions only exercise part of CRITICAL_DISPLAY_STATE_EVENT_TYPES. Entries like plan_approved, thread_changed, thread_created, thread_deleted, mode_changed, model_changed, subagent_model_changed, tool_input_end, tool_end, and subagent_end can stop flushing immediately without this suite noticing. A small table-driven test over the exported set would keep the scheduler contract and tests from drifting.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/harness/display-state.test.ts` around lines 1275 - 1341,
Add a table-driven test that iterates over the exported
CRITICAL_DISPLAY_STATE_EVENT_TYPES and verifies each event causes an immediate
flush: subscribe a mock listener via harness.subscribeDisplayState (using the
same windowMs/maxWaitMs), loop over CRITICAL_DISPLAY_STATE_EVENT_TYPES and for
each type call emit(harness, { type, ...minimalPayloadForType }) (use generic
minimal payloads or a small mapping for types that require fields), and assert
the listener was called once per emit and that its received state reflects the
event (or at least that a call occurred). Reference
CRITICAL_DISPLAY_STATE_EVENT_TYPES, emit, harness.subscribeDisplayState and the
existing listener assertions to replace the duplicated individual-case checks
with this single table-driven assertion to cover all critical events.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/src/content/en/reference/harness/harness-class.mdx`:
- Around line 928-949: Clarify in the subscribeDisplayState docs that the
coalescing options (windowMs, maxWaitMs) do not apply to certain critical
lifecycle updates: explicitly state that approvals, errors, thread/model
changes, and completion events are flushed immediately (bypass the coalescing
window) by the display-state-scheduler logic; mention that subscribeDisplayState
still does not invoke the listener immediately (use getDisplayState for initial
render) and add a short note so UI/SSE/TUI consumers know these specific updates
have no guaranteed latency bound.

---

Nitpick comments:
In `@packages/core/src/harness/display-state.test.ts`:
- Around line 1275-1341: Add a table-driven test that iterates over the exported
CRITICAL_DISPLAY_STATE_EVENT_TYPES and verifies each event causes an immediate
flush: subscribe a mock listener via harness.subscribeDisplayState (using the
same windowMs/maxWaitMs), loop over CRITICAL_DISPLAY_STATE_EVENT_TYPES and for
each type call emit(harness, { type, ...minimalPayloadForType }) (use generic
minimal payloads or a small mapping for types that require fields), and assert
the listener was called once per emit and that its received state reflects the
event (or at least that a call occurred). Reference
CRITICAL_DISPLAY_STATE_EVENT_TYPES, emit, harness.subscribeDisplayState and the
existing listener assertions to replace the duplicated individual-case checks
with this single table-driven assertion to cover all critical events.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 97401741-c26c-48f6-a049-27ff8cf731a8

📥 Commits

Reviewing files that changed from the base of the PR and between 3604a3a and 1038e35.

📒 Files selected for processing (7)

• .changeset/five-hands-punch.md
• docs/src/content/en/reference/harness/harness-class.mdx
• packages/core/src/harness/display-state-scheduler.ts
• packages/core/src/harness/display-state.test.ts
• packages/core/src/harness/harness.ts
• packages/core/src/harness/index.ts
• packages/core/src/harness/types.ts

✅ Files skipped from review due to trivial changes (2)

• packages/core/src/harness/index.ts
• .changeset/five-hands-punch.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/core/src/harness/harness.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Document that critical lifecycle updates bypass the coalescing window.

This reads like windowMs/maxWaitMs apply to every snapshot, but packages/core/src/harness/display-state-scheduler.ts:8-27 flushes approvals, errors, thread/model changes, and completion events immediately. Calling that out here will keep UI consumers from treating the timing options as hard latency bounds for all updates.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/src/content/en/reference/harness/harness-class.mdx` around lines 928 -
949, Clarify in the subscribeDisplayState docs that the coalescing options
(windowMs, maxWaitMs) do not apply to certain critical lifecycle updates:
explicitly state that approvals, errors, thread/model changes, and completion
events are flushed immediately (bypass the coalescing window) by the
display-state-scheduler logic; mention that subscribeDisplayState still does not
invoke the listener immediately (use getDisplayState for initial render) and add
a short note so UI/SSE/TUI consumers know these specific updates have no
guaranteed latency bound.