Skip to content

fix(core): array textStream/elementStream no longer keep stale partial elements - #25278

Merged
abhiaiyer91 merged 1 commit into
mainfrom
factory/issue-25208
Sep 28, 2026
Merged

abhiaiyer91 merged 1 commit into
mainfrom
factory/issue-25208

Conversation

@mastra-platform

@mastra-platform mastra-platform Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Summary

When an agent streams structured output with an array schema and the provider streams token by token, the partial JSON parser can yield the last element before it's complete (e.g. {a:1}). A later chunk then completes that same element ({a:1,b:2}). textStream and elementStream only wrote out elements at new indices, so they kept the incomplete version and didn't match the final object.

Both streams now hold back the last element of each chunk until a following element or the end of the stream shows it's complete. Elements are always taken from the latest chunk. The earlier #18758 behaviour stays the same: a single chunk is still written as one closed JSON string, empty arrays come out as [], and the text is always valid JSON.

The trade-off is that each element arrives one element later than before.

Fixes #25208 (the fix follows the approach in #25138).

Changes

  • packages/core/src/stream/base/output-format-handlers.ts: createJsonTextStreamTransformer holds back the last element and writes it on flush.
  • packages/core/src/stream/base/output.ts: elementStream holds back the last element and publishes it on flush.
  • Tests and changeset.

Test plan

  • 2 new transformer tests and 2 new end-to-end MastraModelOutput tests (textStream and elementStream). All 4 fail without the fix and pass with it.
  • vitest run src/stream: 346 tests pass.
  • pnpm --filter ./packages/core check (tsc) passes.

ELI5

When an array item arrives in pieces, the stream waits before sharing the newest item. This prevents consumers from receiving an unfinished item when later chunks add its missing fields.

Changes

  • Updated textStream to track the latest array and hold back its trailing element until a later element or stream end.
  • Updated elementStream to hold back its trailing element and publish remaining elements at stream end.
  • Added regression tests for elements completed in place across chunks and array-valued structured output.
  • Added a patch changeset for @mastra/core.

This delays publication of each trailing element. Test execution results were not provided.

…ementStream

Token-level providers can complete an array element in place across chunks.
The streams emitted each element as soon as its index appeared, so they kept
stale partial elements that diverged from the final object. Emit an element
only once a later element or stream end proves it complete.

Fixes #25208

Co-Authored-By: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
@dane-ai-mastra

Copy link
Copy Markdown
Contributor

PR triage

Linked issue check skipped for excluded profile @mastra-platform[bot].


Changed test gate

Changed Test Gate is pending. The Changed Test Gate / changed-tests check will update the test label when it completes.

@vercel

vercel Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
mastra-docs-1.x Ready Ready Preview Sep 27, 2026 11:23pm UTC
mastra-playground-ui Ready Ready Preview Sep 27, 2026 11:23pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
mastra-studio-preview Ignored Ignored Preview Sep 27, 2026 11:23pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Sep 27, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d284118

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

This PR includes changesets to release 26 packages
Name Type
@mastra/core Patch
@mastra/code-sdk Patch
mastracode Patch
@mastra/factory 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/react Patch
@mastra/playground-ui Patch
@mastra/deployer Patch
@mastra/server Patch
create-mastra Patch
create-factory Patch
@mastra/temporal Patch
@mastra/elysia Patch
@mastra/express Patch
@mastra/fastify Patch
@mastra/hono Patch
@mastra/koa Patch
@mastra/nestjs Patch
@mastra/next Patch
@mastra/tanstack-start 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

@coderabbitai

coderabbitai Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: mastra-ai/mastra/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: a0615ceb-bc00-4ec3-8501-29e1332a6bca

📥 Commits

Reviewing files that changed from the base of the PR and between c0e2145 and d284118.

📒 Files selected for processing (5)
  • .changeset/array-stream-partial-elements.md
  • packages/core/src/stream/base/output-format-handlers.test.ts
  • packages/core/src/stream/base/output-format-handlers.ts
  • packages/core/src/stream/base/output.test.ts
  • packages/core/src/stream/base/output.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.


Walkthrough

Array structured output streams now publish array elements after later chunks complete them. The text stream emits valid JSON that includes completed elements, and the element stream publishes those elements at completion.

Changes

Array structured output streams

Layer / File(s) Summary
JSON text stream completion
packages/core/src/stream/base/output-format-handlers.ts, packages/core/src/stream/base/output-format-handlers.test.ts
The JSON transformer withholds the trailing array element while more chunks may update it. On flush, it emits the remaining elements and closes the array. Tests cover elements that gain fields in later chunks.
Element stream completion and output tests
packages/core/src/stream/base/output.ts, packages/core/src/stream/base/output.test.ts, .changeset/array-stream-partial-elements.md
The element stream withholds the trailing element until it is complete. Tests check the streamed text, final object, and emitted elements for array output. The changeset documents the patch.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to d2841

Array elements are held until complete, and no actionable merge-blocking risk remains after normal checks.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the fix for stale partial array elements in textStream and elementStream. It is longer than the preferred 50-character limit and uses lowercase conventional-commit form…
Linked Issues check ✅ Passed The PR meets the coding requirements in issue #25208. createJsonTextStreamTransformer tracks the latest array, holds back its trailing element, and emits the latest completed value on a later chunk …
Out of Scope Changes check ✅ Passed The changes stay within issue #25208. The implementation fixes array streaming, the tests verify the regression, and the core changeset documents the fix. No unrelated product behavior or files are ch…
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files. (1 skipped: 1 …
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/core/src/stream/base/output-format-handlers.test.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

packages/core/src/stream/base/output-format-handlers.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

packages/core/src/stream/base/output.test.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

  • 1 others

Comment @coderabbitai help to get the list of available commands.

@mastra-platform

Copy link
Copy Markdown
Contributor Author

Verdict: approve

Reviewed head: d284118f1766a1f7bf1961e970fc21f4d8553f56

Findings

  • Cause confirmed: both createJsonTextStreamTransformer (output-format-handlers.ts) and elementStream (output.ts) wrote array elements the first time their index appeared. The partial JSON parser emits the trailing element before it is complete, and later chunks complete it at the same index, so the stale first parse was the one kept. The fix is at the cause: only elements followed by another element are emitted, and the rest come from the latest chunk on flush.
  • The [BUG] Array textStream emits invalid JSON when the first object chunk already has elements #18758 contract still holds: a single chunk is emitted closed, an empty chunk gives [], and the incremental path gives valid JSON. The buffered first chunk is no longer replayed from stale data, because the second chunk supplies the elements.
  • Non-blocking trade-off: each element now arrives one step later, and the last element arrives only at stream end. This is inherent to the fix and is documented in the PR.

Approach: this matches the design I wrote before reading the diff: hold back the trailing element until a later element or the end of the stream. It adds no flags or config.

Issue and intent: closes #25208 (bug, status: auto-triaged). The implemented behavior matches the issue's expected outcome.

Verification

  • pnpm exec vitest run src/stream (packages/core): 18 files, 348 tests passed.
  • tsc --noEmit -p packages/core: passed.
  • Test-on-base: I reverted only the two source files to base and ran the two test files. All 4 new tests failed (4 failed | 103 passed), so they detect the bug.
  • CI: some checks were still running at review time (Build, changed-tests). This is advisory only.

Existing review disposition: CodeRabbit completed with no inline findings, and there are no human reviews. The bot comments (triage, changeset, Vercel) are informational.

Adversarial check: the strongest case against is that elementStream consumers now see the final element only at stream end, or never if the stream errors. It fails as a blocker because the alternative is emitting data that contradicts the validated object, and in the error case the old code would also have emitted an incomplete element.

Assumptions: a delay of one element is an acceptable latency cost for correctness.

Open questions: none.

Review runtime: anthropic/claude-opus-5-5, reasoning setting: low.

@mastra-platform mastra-platform Bot added the status:auto-approved Factory review auto-approved label Sep 27, 2026
@abhiaiyer91
abhiaiyer91 merged commit 43fbe75 into main Sep 28, 2026
90 of 91 checks passed
@abhiaiyer91
abhiaiyer91 deleted the factory/issue-25208 branch September 28, 2026 01:41

This branch was successfully deployed

2 active deployments
Preview – mastra-playground-ui — d284118f Deployed Sep 27, 2026 by vercel[bot]
Preview – mastra-docs-1.x — d284118f Deployed Sep 27, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status:auto-approved Factory review auto-approved tests: green ✅ Changed tests failed against base as expected

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Array structured output textStream/elementStream keep the stale partial element when a later chunk completes it in place

1 participant