From b1dd43256b9f1fcb4f1094e7d06bb14a7f1cd326 Mon Sep 17 00:00:00 2001 From: Leo <108278866+leoisadev1@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:37:47 -0500 Subject: [PATCH 1/4] fix(playground): show the maxSteps warning only when a run used every step Studio warned "Agent stopped because it reached maxSteps" after any run whose last step called a tool. Core also ends runs that way when a stopWhen matches or a client tool ends the turn, so agents that end each turn with a question tool saw the warning every turn. The check now also requires a known maxSteps and that the run used at least that many steps, not counting processor retry steps, which is how core counts the step budget. Fixes #29612 Co-Authored-By: Claude Opus 5.5 --- .changeset/quiet-steps-warn.md | 5 ++ .../chat/__tests__/chat-provider.test.tsx | 83 +++++++++++++++++++ .../chat/__tests__/fixtures/question-agent.ts | 63 ++++++++++++++ .../lib/ai-ui/chat/use-chat-send-handler.ts | 2 +- .../__tests__/stream-error-message.test.ts | 76 ++++++++++------- .../src/services/stream-error-message.ts | 33 +++++++- 6 files changed, 229 insertions(+), 33 deletions(-) create mode 100644 .changeset/quiet-steps-warn.md create mode 100644 packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts diff --git a/.changeset/quiet-steps-warn.md b/.changeset/quiet-steps-warn.md new file mode 100644 index 00000000000..b95d505d46c --- /dev/null +++ b/.changeset/quiet-steps-warn.md @@ -0,0 +1,5 @@ +--- +'mastra': patch +--- + +Fixed Studio warning that an agent "reached maxSteps" after every turn that ended on a tool call. The warning now appears only when the run used every step in its `maxSteps` budget, so a turn that `stopWhen` ended after one tool call, such as a question for the user, no longer shows it. Fixes [#29612](https://github.com/mastra-ai/mastra/issues/29612). diff --git a/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx b/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx index 845369c964f..ca5ee07c4da 100644 --- a/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx +++ b/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx @@ -1,4 +1,5 @@ import type { MastraDBMessage } from '@mastra/core/agent/message-list'; +import type { ChunkType } from '@mastra/core/stream'; import { useChatMessages, useChatModelContext, @@ -25,6 +26,7 @@ import { emptyApprovalHistory, generatedApprovalResponse, } from './fixtures/nested-approval'; +import { stopAfterQuestion, streamQuestionAgent } from './fixtures/question-agent'; import { acceptedToolRun, emptyMcpServers, @@ -377,6 +379,87 @@ describe('ChatProvider', () => { ); }); + // A finish reason of 'tool-calls' only says the last step called a tool. A stopWhen + // match ends a run the same way, so Studio must not read it as running out of steps. (#29612) + describe('when a run ends on a tool call', () => { + const MAX_STEPS_WARNING = /reached maxSteps/; + + const renderRun = async ({ maxSteps, chunks }: { maxSteps: number; chunks: ChunkType[] }) => { + let requested = false; + server.use( + http.post(`${BASE_URL}/api/agents/agent-1/stream`, () => { + requested = true; + return new HttpResponse( + new ReadableStream({ + start(controller) { + for (const chunk of chunks) + controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`)); + controller.close(); + }, + }), + { headers: { 'content-type': 'text/event-stream' } }, + ); + }), + http.get(`${BASE_URL}/api/mcp/v0/servers`, () => HttpResponse.json(emptyMcpServers)), + ...baseHandlers([]), + ); + const Transcript = () => { + const messages = useChatMessages(); + const send = useChatSend(); + const { isRunning } = useChatRunning(); + return ( + <> + + {isRunning ? 'Running' : 'Stopped'} + {messages.map(message => ( + + ))} + + ); + }; + render( + + + + + , + ); + fireEvent.click(screen.getByRole('button', { name: 'Send' })); + await waitFor(() => expect(requested).toBe(true)); + await waitFor(() => expect(screen.getByTestId('run-state').textContent).toBe('Stopped')); + }; + + // Both runs end the same way on the wire; only the step count tells them apart. + const expectToolCallFinish = (chunks: ChunkType[], steps: number) => + expect(chunks.at(-1)).toMatchObject({ + type: 'finish', + payload: { stepResult: { reason: 'tool-calls' }, output: { steps: Array(steps).fill(expect.anything()) } }, + }); + + it('shows no maxSteps warning when stopWhen ended the turn after the question', async () => { + const chunks = await streamQuestionAgent({ maxSteps: 10, stopWhen: stopAfterQuestion }); + expectToolCallFinish(chunks, 1); + + await renderRun({ maxSteps: 10, chunks }); + + expect(screen.queryByText(MAX_STEPS_WARNING)).toBeNull(); + }); + + it('warns when the run used every step it had', async () => { + const chunks = await streamQuestionAgent({ maxSteps: 3 }); + expectToolCallFinish(chunks, 3); + + await renderRun({ maxSteps: 3, chunks }); + + expect(await screen.findByText(/reached maxSteps \(3\)/)).toBeTruthy(); + }); + }); + describe('when a later run starts after an interrupted run', () => { it.each(['legacy', 'signals'])( 'keeps historical calls incomplete while the new %s run progresses', diff --git a/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts b/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts new file mode 100644 index 00000000000..de75bdfd3f2 --- /dev/null +++ b/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts @@ -0,0 +1,63 @@ +import { Agent } from '@mastra/core/agent'; +import type { ChunkType } from '@mastra/core/stream'; +import { MastraLanguageModelV2Mock } from '@mastra/core/test-utils/llm-mock'; +import { createTool } from '@mastra/core/tools'; +import { z } from 'zod'; + +const askQuestion = createTool({ + id: 'askQuestion', + description: 'Show the user a question with answer buttons', + inputSchema: z.object({ question: z.string() }), + execute: async () => ({ shown: true }), +}); + +type StreamOptions = NonNullable[1]>; + +/** Ends the turn once the agent has asked its question, like an agent whose question tool waits for the user. */ +export const stopAfterQuestion: NonNullable = ({ steps }) => + (steps.at(-1)?.toolCalls ?? []).some(call => call.toolName === 'askQuestion'); + +/** + * Runs a real agent whose model calls `askQuestion` on every step, and returns + * the chunks its stream produced, as the agent stream route sends them. + */ +export const streamQuestionAgent = async ( + options: Pick, +): Promise => { + let modelCalls = 0; + const agent = new Agent({ + id: 'agent-1', + name: 'Poster agent', + instructions: 'Ask the user which style they want before designing.', + tools: { askQuestion }, + model: new MastraLanguageModelV2Mock({ + doStream: async () => { + modelCalls++; + return { + stream: new ReadableStream({ + start(controller) { + controller.enqueue({ type: 'stream-start', warnings: [] }); + controller.enqueue({ + type: 'tool-call', + toolCallId: `call-${modelCalls}`, + toolName: 'askQuestion', + input: JSON.stringify({ question: 'Which style?' }), + }); + controller.enqueue({ + type: 'finish', + finishReason: 'tool-calls', + usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 }, + }); + controller.close(); + }, + }), + }; + }, + }), + }); + + const output = await agent.stream('Make me a poster', options); + const chunks: ChunkType[] = []; + for await (const chunk of output.fullStream) chunks.push(chunk); + return chunks; +}; diff --git a/packages/playground/src/lib/ai-ui/chat/use-chat-send-handler.ts b/packages/playground/src/lib/ai-ui/chat/use-chat-send-handler.ts index e2032b4163b..2183303ebf4 100644 --- a/packages/playground/src/lib/ai-ui/chat/use-chat-send-handler.ts +++ b/packages/playground/src/lib/ai-ui/chat/use-chat-send-handler.ts @@ -343,7 +343,7 @@ export const useChatSendHandler = ({ onChunk: async (chunk: any) => { delivered = true; if (chunk.type === 'finish') { - if (isMaxStepsFinishChunk(chunk)) { + if (isMaxStepsFinishChunk({ chunk, maxSteps: deps.maxSteps })) { setStreamErrors(prev => [...prev, buildMaxStepsStreamErrorMessage(chunk, deps.maxSteps)]); } await refreshThreadList?.(); diff --git a/packages/playground/src/services/__tests__/stream-error-message.test.ts b/packages/playground/src/services/__tests__/stream-error-message.test.ts index fce319aeae4..b42fca4937c 100644 --- a/packages/playground/src/services/__tests__/stream-error-message.test.ts +++ b/packages/playground/src/services/__tests__/stream-error-message.test.ts @@ -2,39 +2,53 @@ import { describe, expect, it } from 'vitest'; import { buildStreamErrorMessage, isMaxStepsFinishChunk } from '../stream-error-message'; describe('stream error messages', () => { - it('only treats terminal tool-call finish chunks as maxSteps exhaustion', () => { - expect( - isMaxStepsFinishChunk({ - type: 'finish', - payload: { - stepResult: { - reason: 'tool-calls', - }, - }, - }), - ).toBe(true); + describe('when a run ends on a tool call (#29612)', () => { + const finish = ({ + type = 'finish', + reason = 'tool-calls', + steps, + }: { + type?: string; + reason?: string; + steps: unknown[]; + }) => ({ + type, + payload: { stepResult: { reason }, output: { steps } }, + }); + const step = (finishReason: string) => ({ finishReason }); - expect( - isMaxStepsFinishChunk({ - type: 'step-finish', - payload: { - stepResult: { - reason: 'tool-calls', - }, - }, - }), - ).toBe(false); + it('warns only once every step in the budget is used', () => { + const threeToolSteps = [step('tool-calls'), step('tool-calls'), step('tool-calls')]; + expect(isMaxStepsFinishChunk({ chunk: finish({ steps: threeToolSteps }), maxSteps: 3 })).toBe(true); + expect(isMaxStepsFinishChunk({ chunk: finish({ steps: threeToolSteps }), maxSteps: 10 })).toBe(false); + }); - expect( - isMaxStepsFinishChunk({ - type: 'finish', - payload: { - stepResult: { - reason: 'stop', - }, - }, - }), - ).toBe(false); + it('does not count processor retry steps against the budget', () => { + const steps = [step('retry'), step('tool-calls'), step('tool-calls')]; + expect(isMaxStepsFinishChunk({ chunk: finish({ steps }), maxSteps: 3 })).toBe(false); + expect(isMaxStepsFinishChunk({ chunk: finish({ steps }), maxSteps: 2 })).toBe(true); + }); + + it('does not warn without a known limit or step list', () => { + expect(isMaxStepsFinishChunk({ chunk: finish({ steps: [step('tool-calls')] }), maxSteps: undefined })).toBe( + false, + ); + expect( + isMaxStepsFinishChunk({ + chunk: { type: 'finish', payload: { stepResult: { reason: 'tool-calls' } } }, + maxSteps: 1, + }), + ).toBe(false); + }); + + it('ignores step-finish chunks and runs the model ended', () => { + expect( + isMaxStepsFinishChunk({ chunk: finish({ type: 'step-finish', steps: [step('tool-calls')] }), maxSteps: 1 }), + ).toBe(false); + expect(isMaxStepsFinishChunk({ chunk: finish({ reason: 'stop', steps: [step('stop')] }), maxSteps: 1 })).toBe( + false, + ); + }); }); it('preserves human-readable error payloads', () => { diff --git a/packages/playground/src/services/stream-error-message.ts b/packages/playground/src/services/stream-error-message.ts index 43dfc0503f1..ea65b5b55ac 100644 --- a/packages/playground/src/services/stream-error-message.ts +++ b/packages/playground/src/services/stream-error-message.ts @@ -14,11 +14,24 @@ type FinishChunkLike = { stepResult?: { reason?: unknown; }; + output?: { + steps?: unknown; + }; }; }; const MAX_STEPS_FINISH_REASON = 'tool-calls'; +const isRetryStep = (step: unknown) => + typeof step === 'object' && step !== null && 'finishReason' in step && step.finishReason === 'retry'; + +/** + * The steps a run spent from its maxSteps budget. A processor retry re-runs its + * step, so core's step limit does not count it, and neither does this. + */ +const countBudgetedSteps = (steps: unknown) => + Array.isArray(steps) ? steps.filter(step => !isRetryStep(step)).length : undefined; + const getMaxStepsErrorText = (maxSteps?: number) => { const limit = typeof maxSteps === 'number' ? ` (${maxSteps})` : ''; return `Agent stopped because it reached maxSteps${limit} while tool calls were still pending. Increase maxSteps in advanced settings and try again.`; @@ -31,7 +44,25 @@ const getFinishReason = (chunk: FinishChunkLike) => { return typeof reason === 'string' ? reason : undefined; }; -export const isMaxStepsFinishChunk = (chunk: FinishChunkLike) => getFinishReason(chunk) === MAX_STEPS_FINISH_REASON; +/** + * True when a run stopped because it used its whole step budget while the model + * still wanted to call tools. A `'tool-calls'` finish reason alone only says the + * last step called a tool: a `stopWhen` match or a client tool ends a run the + * same way (#29612). So the run must also have used every step in `maxSteps`. + * Without a known limit there is nothing to compare against, so no warning. + */ +export const isMaxStepsFinishChunk = ({ + chunk, + maxSteps, +}: { + chunk: FinishChunkLike; + maxSteps: number | undefined; +}) => { + if (getFinishReason(chunk) !== MAX_STEPS_FINISH_REASON) return false; + if (typeof maxSteps !== 'number' || maxSteps < 1) return false; + const usedSteps = countBudgetedSteps(chunk.payload?.output?.steps); + return usedSteps !== undefined && usedSteps >= maxSteps; +}; /** * Build a `MastraDBMessage` representing a stream `error` chunk so it can be From 2c8f6c72fbc3eb862255390693e210299138ff5a Mon Sep 17 00:00:00 2001 From: Leo <108278866+leoisadev1@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:04:11 -0500 Subject: [PATCH 2/4] fix(core, playground): keep the step count on thread broadcast finish chunks Studio's default signal transport reads a run's finish chunk from the thread subscription, whose copies drop output.steps. The maxSteps check then never saw a step count and missed real exhaustion. Broadcast finish copies now keep output.stepCount (steps that count against maxSteps, retries excluded), and Studio falls back to it when steps are absent. Co-Authored-By: Claude Opus 5.5 --- .changeset/heavy-files-doubt.md | 5 + ...read-stream-broadcast-sanitization.test.ts | 116 +++++++++++++++++- .../core/src/background-tasks/manager.test.ts | 3 +- .../core/src/stream/strip-model-snapshots.ts | 24 +++- packages/core/src/stream/types.ts | 6 + .../chat/__tests__/chat-provider.test.tsx | 58 ++++++--- .../chat/__tests__/fixtures/question-agent.ts | 42 +++++-- .../__tests__/stream-error-message.test.ts | 9 ++ .../src/services/stream-error-message.ts | 15 ++- 9 files changed, 235 insertions(+), 43 deletions(-) create mode 100644 .changeset/heavy-files-doubt.md diff --git a/.changeset/heavy-files-doubt.md b/.changeset/heavy-files-doubt.md new file mode 100644 index 00000000000..4bdba53b738 --- /dev/null +++ b/.changeset/heavy-files-doubt.md @@ -0,0 +1,5 @@ +--- +'@mastra/core': patch +--- + +Thread subscription copies of an agent's `finish` chunk now include `output.stepCount`, the number of steps that count against `maxSteps`. These copies leave out `output.steps` to stay small, so subscribers had no way to tell whether a run used its whole step budget. Processor retry steps are not counted, matching how `maxSteps` is enforced. Fixes [#29612](https://github.com/mastra-ai/mastra/issues/29612). diff --git a/packages/core/src/agent/__tests__/thread-stream-broadcast-sanitization.test.ts b/packages/core/src/agent/__tests__/thread-stream-broadcast-sanitization.test.ts index 0140d8cb564..b6bc78e0dac 100644 --- a/packages/core/src/agent/__tests__/thread-stream-broadcast-sanitization.test.ts +++ b/packages/core/src/agent/__tests__/thread-stream-broadcast-sanitization.test.ts @@ -11,11 +11,16 @@ */ import { describe, expect, it } from 'vitest'; +import { z } from 'zod/v4'; + import { PubSub } from '../../events/pubsub'; import type { Event } from '../../events/types'; +import { Mastra } from '../../mastra'; import type { MastraModelOutput } from '../../stream/base/output'; -import type { Agent } from '../agent'; +import { createTool } from '../../tools'; +import { Agent } from '../agent'; import { AgentThreadStreamRuntime } from '../thread-stream-runtime'; +import { convertArrayToReadableStream, MockLanguageModelV2 } from './mock-model'; class CapturePubSub extends PubSub { events: Array<{ topic: string; event: Event }> = []; @@ -46,7 +51,7 @@ function fakeOutput(runId: string, parts: unknown[]): MastraModelOutput { } const MARKER = 'RAW_MODEL_REQUEST_BODY_'.repeat(64); -const agent = { id: 'sanitize-agent' } as Agent; +const agent = { id: 'sanitize-agent' } as unknown as Agent; describe('thread-stream broadcast sanitization', () => { it('drops raw model request bookkeeping from broadcast parts without mutating the originals', async () => { @@ -110,10 +115,15 @@ describe('thread-stream broadcast sanitization', () => { expect(broadcastStepStart!.payload).toEqual({ messageId: 'msg-1', warnings: [] }); for (const part of [broadcastStepFinish!, broadcastFinish!]) { expect(part.payload.metadata).toEqual({ providerMetadata: { test: { keep: true } } }); - expect(part.payload.output).toEqual({ usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 } }); expect('messages' in part.payload).toBe(false); expect(part.payload.stepResult).toEqual({ reason: 'stop' }); } + expect(broadcastStepFinish!.payload.output).toEqual({ usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 } }); + // The run's finish keeps how many steps it took, without the steps themselves. + expect(broadcastFinish!.payload.output).toEqual({ + usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 }, + stepCount: 1, + }); // The caller's chunks are untouched — only the broadcast copies are rewritten. expect(stepStart.payload.request.body).toBe(MARKER); @@ -178,7 +188,7 @@ describe('thread-stream broadcast sanitization', () => { const broadcastChildDelegation = broadcast.payload.output; const broadcastChildFinish = broadcastChildDelegation.payload.output; - expect(broadcastChildFinish.payload.output).toEqual({ text: 'child answer' }); + expect(broadcastChildFinish.payload.output).toEqual({ text: 'child answer', stepCount: 1 }); expect(broadcastChildFinish.payload.metadata).toEqual({ providerMetadata: { test: { keep: true } } }); expect('messages' in broadcastChildFinish.payload).toBe(false); expect(JSON.stringify(broadcast)).not.toContain(MARKER); @@ -251,4 +261,102 @@ describe('thread-stream broadcast sanitization', () => { // broadcast retains only control metadata and text. expect(broadcastJson.length).toBeLessThan(rawSize / 10); }); + + // Subscribers such as Studio tell a run that used its whole maxSteps budget from one a + // stopWhen ended early by its step count, so the broadcast finish keeps that count. (#29612) + describe('step count on the broadcast finish', () => { + const usage = { inputTokens: 1, outputTokens: 1, totalTokens: 2 }; + + it.each([ + { maxSteps: 3, stopOnFirstStep: false, stepCount: 3 }, + { maxSteps: 10, stopOnFirstStep: true, stepCount: 1 }, + ])( + 'carries $stepCount for a real run with maxSteps $maxSteps (stopWhen on step 1: $stopOnFirstStep)', + async ({ maxSteps, stopOnFirstStep, stepCount }) => { + let calls = 0; + const realAgent = new Agent({ + id: 'step-count-agent', + name: 'Step count agent', + instructions: 'Keep looking things up.', + tools: { + lookup: createTool({ + id: 'lookup', + description: 'look something up', + inputSchema: z.object({}), + execute: async () => ({ found: true }), + }), + }, + model: new MockLanguageModelV2({ + doStream: async () => ({ + rawCall: { rawPrompt: null, rawSettings: {} }, + warnings: [], + stream: convertArrayToReadableStream([ + { type: 'stream-start' as const, warnings: [] }, + { type: 'tool-call' as const, toolCallId: `call-${++calls}`, toolName: 'lookup', input: '{}' }, + { type: 'finish' as const, finishReason: 'tool-calls' as const, usage }, + ]), + }), + }), + }); + new Mastra({ agents: { realAgent }, logger: false }); + const memory = { thread: 'step-count-thread', resource: 'step-count-user' }; + const subscription = await realAgent.subscribeToThread({ + threadId: memory.thread, + resourceId: memory.resource, + }); + try { + const output = await realAgent.stream('go', { + maxSteps, + ...(stopOnFirstStep ? { stopWhen: () => true } : {}), + memory, + }); + const local = await output.getFullOutput(); + expect(local.steps).toHaveLength(stepCount); + + let broadcastFinish: any; + for await (const part of subscription.stream) { + if (part.type === 'finish') { + broadcastFinish = part; + break; + } + } + expect(broadcastFinish.payload.stepResult.reason).toBe('tool-calls'); + expect(broadcastFinish.payload.output.steps).toBeUndefined(); + expect(broadcastFinish.payload.output.stepCount).toBe(stepCount); + } finally { + subscription.unsubscribe(); + } + }, + ); + + it('does not count processor retry steps, which the step limit ignores', async () => { + const runtime = new AgentThreadStreamRuntime(); + const pubsub = new CapturePubSub(); + const finish = { + type: 'finish', + payload: { + stepResult: { reason: 'tool-calls' }, + output: { + usage, + steps: [{ finishReason: 'retry' }, { finishReason: 'tool-calls' }, { finishReason: 'tool-calls' }], + }, + }, + }; + await runtime.registerRun( + agent, + fakeOutput('retry-run', [finish]), + { memory: { thread: 'retry-thread', resource: 'sanitize-user' } }, + pubsub, + ); + const broadcastFinish = async () => + pubsub.events + .map(({ event }) => event.data as { type?: string; part?: { type: string; payload: Record } }) + .find(data => data?.type === 'stream-part' && data.part?.type === 'finish')?.part; + const deadline = Date.now() + 2000; + while (!(await broadcastFinish()) && Date.now() < deadline) { + await new Promise(resolve => setTimeout(resolve, 10)); + } + expect((await broadcastFinish())?.payload.output).toEqual({ usage, stepCount: 2 }); + }); + }); }); diff --git a/packages/core/src/background-tasks/manager.test.ts b/packages/core/src/background-tasks/manager.test.ts index fc308734dba..85e68ba88de 100644 --- a/packages/core/src/background-tasks/manager.test.ts +++ b/packages/core/src/background-tasks/manager.test.ts @@ -2306,7 +2306,8 @@ describe('BackgroundTaskManager', () => { }); expect(finish.payload).toEqual({ stepResult: { reason: 'stop' }, - output: { usage: { totalTokens: 3 } }, + // The steps are dropped; only how many there were stays. + output: { usage: { totalTokens: 3 }, stepCount: 1 }, metadata: {}, response: { id: 'resp-1', modelId: 'gpt-5' }, }); diff --git a/packages/core/src/stream/strip-model-snapshots.ts b/packages/core/src/stream/strip-model-snapshots.ts index 9d7d86a7e7a..a9a6cfbbbbf 100644 --- a/packages/core/src/stream/strip-model-snapshots.ts +++ b/packages/core/src/stream/strip-model-snapshots.ts @@ -1,10 +1,21 @@ +/** + * The steps that count against `maxSteps`. A processor retry re-runs its step, + * so the loop does not count it toward the limit, and neither does this. + */ +function countBudgetedSteps(steps: unknown[]): number { + return steps.filter( + step => !(typeof step === 'object' && step !== null && 'finishReason' in step && step.finishReason === 'retry'), + ).length; +} + /** * Removes the model request/history snapshots that agent `step-start`, * `step-finish` and `finish` chunks carry (full prompt, file parts, message * history, cumulative steps). Used for copies of chunks that are fanned out to - * other subscribers, which don't need those fields. Only the given chunk is - * inspected; callers decide which nested chunks to pass in. Returns the same - * reference when nothing was removed. + * other subscribers, which don't need those fields. A `finish` chunk keeps the + * number of steps as `output.stepCount`. Only the given chunk is inspected; + * callers decide which nested chunks to pass in. Returns the same reference + * when nothing was removed. */ export function stripModelSnapshots(chunk: T): T { if (!chunk || typeof chunk !== 'object') return chunk; @@ -27,8 +38,11 @@ export function stripModelSnapshots(chunk: T): T { changed = true; } if (p.output && typeof p.output === 'object' && 'steps' in p.output) { - const { steps: _steps, ...output } = p.output as Record; - next.output = output; + const { steps, ...output } = p.output as Record; + // Subscribers still need to know how many steps the run took, e.g. to tell a run + // that used its whole maxSteps budget from one a stopWhen ended early. + next.output = + type === 'finish' && Array.isArray(steps) ? { ...output, stepCount: countBudgetedSteps(steps) } : output; changed = true; } if ('messages' in p) { diff --git a/packages/core/src/stream/types.ts b/packages/core/src/stream/types.ts index a062ffae1be..26210134911 100644 --- a/packages/core/src/stream/types.ts +++ b/packages/core/src/stream/types.ts @@ -283,6 +283,12 @@ interface FinishPayload[]; + /** + * Number of steps that count against `maxSteps` (processor retry steps don't). + * Set on slimmed copies of this chunk, such as thread subscription broadcasts, + * which drop `steps`. + */ + stepCount?: number; }; metadata: { providerMetadata?: ProviderMetadata; diff --git a/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx b/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx index ca5ee07c4da..75fc7882931 100644 --- a/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx +++ b/packages/playground/src/lib/ai-ui/chat/__tests__/chat-provider.test.tsx @@ -26,7 +26,7 @@ import { emptyApprovalHistory, generatedApprovalResponse, } from './fixtures/nested-approval'; -import { stopAfterQuestion, streamQuestionAgent } from './fixtures/question-agent'; +import { broadcastQuestionAgent, stopAfterQuestion, streamQuestionAgent } from './fixtures/question-agent'; import { acceptedToolRun, emptyMcpServers, @@ -381,24 +381,40 @@ describe('ChatProvider', () => { // A finish reason of 'tool-calls' only says the last step called a tool. A stopWhen // match ends a run the same way, so Studio must not read it as running out of steps. (#29612) - describe('when a run ends on a tool call', () => { + // Studio's default signal transport reads the run from a thread subscription, whose + // chunks are slimmed broadcast copies, so both transports are covered. + describe.each(['legacy', 'signals'] as const)('when a %s run ends on a tool call', transport => { const MAX_STEPS_WARNING = /reached maxSteps/; + const runAgent = transport === 'signals' ? broadcastQuestionAgent : streamQuestionAgent; + + const sse = (chunks: ChunkType[]) => chunks.map(chunk => `data: ${JSON.stringify(chunk)}\n\n`).join(''); const renderRun = async ({ maxSteps, chunks }: { maxSteps: number; chunks: ChunkType[] }) => { + Object.assign(window, { MASTRA_AGENT_SIGNALS: transport === 'signals' ? 'true' : 'false' }); let requested = false; + let subscription: ReadableStreamDefaultController | undefined; server.use( http.post(`${BASE_URL}/api/agents/agent-1/stream`, () => { requested = true; - return new HttpResponse( - new ReadableStream({ - start(controller) { - for (const chunk of chunks) - controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`)); - controller.close(); - }, - }), - { headers: { 'content-type': 'text/event-stream' } }, - ); + return new HttpResponse(sse(chunks), { headers: { 'content-type': 'text/event-stream' } }); + }), + http.post( + `${BASE_URL}/api/agents/agent-1/threads/subscribe`, + () => + new HttpResponse( + new ReadableStream({ + start(controller) { + subscription = controller; + }, + }), + { headers: { 'content-type': 'text/event-stream' } }, + ), + ), + http.post(`${BASE_URL}/api/agents/agent-1/send-message`, () => { + requested = true; + // The run reaches the open thread subscription, as the server broadcasts it. + queueMicrotask(() => subscription?.enqueue(new TextEncoder().encode(sse(chunks)))); + return HttpResponse.json(acceptedToolRun(chunks[0].runId)); }), http.get(`${BASE_URL}/api/mcp/v0/servers`, () => HttpResponse.json(emptyMcpServers)), ...baseHandlers([]), @@ -429,20 +445,22 @@ describe('ChatProvider', () => { , ); + if (transport === 'signals') await waitFor(() => expect(subscription).toBeDefined()); fireEvent.click(screen.getByRole('button', { name: 'Send' })); await waitFor(() => expect(requested).toBe(true)); + await screen.findByText('Make me a poster'); await waitFor(() => expect(screen.getByTestId('run-state').textContent).toBe('Stopped')); + subscription?.close(); }; - // Both runs end the same way on the wire; only the step count tells them apart. - const expectToolCallFinish = (chunks: ChunkType[], steps: number) => - expect(chunks.at(-1)).toMatchObject({ - type: 'finish', - payload: { stepResult: { reason: 'tool-calls' }, output: { steps: Array(steps).fill(expect.anything()) } }, - }); + // Both runs end the same way on the wire; only the number of steps tells them apart. + const expectToolCallFinish = (chunks: ChunkType[], steps: number) => { + expect(chunks.at(-1)).toMatchObject({ type: 'finish', payload: { stepResult: { reason: 'tool-calls' } } }); + expect(chunks.filter(chunk => chunk.type === 'step-finish')).toHaveLength(steps); + }; it('shows no maxSteps warning when stopWhen ended the turn after the question', async () => { - const chunks = await streamQuestionAgent({ maxSteps: 10, stopWhen: stopAfterQuestion }); + const chunks = await runAgent({ maxSteps: 10, stopWhen: stopAfterQuestion }); expectToolCallFinish(chunks, 1); await renderRun({ maxSteps: 10, chunks }); @@ -451,7 +469,7 @@ describe('ChatProvider', () => { }); it('warns when the run used every step it had', async () => { - const chunks = await streamQuestionAgent({ maxSteps: 3 }); + const chunks = await runAgent({ maxSteps: 3 }); expectToolCallFinish(chunks, 3); await renderRun({ maxSteps: 3, chunks }); diff --git a/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts b/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts index de75bdfd3f2..8c4b5ff2fe2 100644 --- a/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts +++ b/packages/playground/src/lib/ai-ui/chat/__tests__/fixtures/question-agent.ts @@ -1,4 +1,5 @@ import { Agent } from '@mastra/core/agent'; +import { Mastra } from '@mastra/core/mastra'; import type { ChunkType } from '@mastra/core/stream'; import { MastraLanguageModelV2Mock } from '@mastra/core/test-utils/llm-mock'; import { createTool } from '@mastra/core/tools'; @@ -12,20 +13,16 @@ const askQuestion = createTool({ }); type StreamOptions = NonNullable[1]>; +type RunOptions = Pick; /** Ends the turn once the agent has asked its question, like an agent whose question tool waits for the user. */ export const stopAfterQuestion: NonNullable = ({ steps }) => (steps.at(-1)?.toolCalls ?? []).some(call => call.toolName === 'askQuestion'); -/** - * Runs a real agent whose model calls `askQuestion` on every step, and returns - * the chunks its stream produced, as the agent stream route sends them. - */ -export const streamQuestionAgent = async ( - options: Pick, -): Promise => { +/** A real agent whose model calls `askQuestion` on every step. */ +const createQuestionAgent = () => { let modelCalls = 0; - const agent = new Agent({ + return new Agent({ id: 'agent-1', name: 'Poster agent', instructions: 'Ask the user which style they want before designing.', @@ -55,9 +52,36 @@ export const streamQuestionAgent = async ( }, }), }); +}; - const output = await agent.stream('Make me a poster', options); +/** The chunks the agent's own stream produced, as the agent stream route sends them. */ +export const streamQuestionAgent = async (options: RunOptions): Promise => { + const output = await createQuestionAgent().stream('Make me a poster', options); const chunks: ChunkType[] = []; for await (const chunk of output.fullStream) chunks.push(chunk); return chunks; }; + +/** + * The chunks a thread subscriber received while the agent ran on `thread-1`, as + * the thread subscribe route sends them to Studio's default signal transport. + * Thread broadcasts are slimmed copies of the run's chunks, not the chunks themselves. + */ +export const broadcastQuestionAgent = async (options: RunOptions): Promise => { + const agent = createQuestionAgent(); + new Mastra({ agents: { agent }, logger: false }); + const memory = { thread: 'thread-1', resource: 'user-1' }; + const subscription = await agent.subscribeToThread({ threadId: memory.thread, resourceId: memory.resource }); + try { + const output = await agent.stream('Make me a poster', { ...options, memory }); + await output.consumeStream(); + const chunks: ChunkType[] = []; + for await (const chunk of subscription.stream) { + chunks.push(chunk); + if (chunk.type === 'finish') break; + } + return chunks; + } finally { + subscription.unsubscribe(); + } +}; diff --git a/packages/playground/src/services/__tests__/stream-error-message.test.ts b/packages/playground/src/services/__tests__/stream-error-message.test.ts index b42fca4937c..142381d4fd3 100644 --- a/packages/playground/src/services/__tests__/stream-error-message.test.ts +++ b/packages/playground/src/services/__tests__/stream-error-message.test.ts @@ -29,6 +29,15 @@ describe('stream error messages', () => { expect(isMaxStepsFinishChunk({ chunk: finish({ steps }), maxSteps: 2 })).toBe(true); }); + it('reads the step count a thread subscription copy carries instead of steps', () => { + const broadcast = (stepCount: number) => ({ + type: 'finish', + payload: { stepResult: { reason: 'tool-calls' }, output: { stepCount } }, + }); + expect(isMaxStepsFinishChunk({ chunk: broadcast(3), maxSteps: 3 })).toBe(true); + expect(isMaxStepsFinishChunk({ chunk: broadcast(1), maxSteps: 10 })).toBe(false); + }); + it('does not warn without a known limit or step list', () => { expect(isMaxStepsFinishChunk({ chunk: finish({ steps: [step('tool-calls')] }), maxSteps: undefined })).toBe( false, diff --git a/packages/playground/src/services/stream-error-message.ts b/packages/playground/src/services/stream-error-message.ts index ea65b5b55ac..fab6481129b 100644 --- a/packages/playground/src/services/stream-error-message.ts +++ b/packages/playground/src/services/stream-error-message.ts @@ -16,6 +16,7 @@ type FinishChunkLike = { }; output?: { steps?: unknown; + stepCount?: unknown; }; }; }; @@ -27,10 +28,14 @@ const isRetryStep = (step: unknown) => /** * The steps a run spent from its maxSteps budget. A processor retry re-runs its - * step, so core's step limit does not count it, and neither does this. + * step, so core's step limit does not count it, and neither does this. Thread + * subscription copies of the chunk, which Studio's signal transport reads, drop + * `steps` and carry core's own count as `stepCount` instead. */ -const countBudgetedSteps = (steps: unknown) => - Array.isArray(steps) ? steps.filter(step => !isRetryStep(step)).length : undefined; +const countBudgetedSteps = (output: NonNullable['output']) => { + if (Array.isArray(output?.steps)) return output.steps.filter(step => !isRetryStep(step)).length; + return typeof output?.stepCount === 'number' ? output.stepCount : undefined; +}; const getMaxStepsErrorText = (maxSteps?: number) => { const limit = typeof maxSteps === 'number' ? ` (${maxSteps})` : ''; @@ -50,6 +55,8 @@ const getFinishReason = (chunk: FinishChunkLike) => { * last step called a tool: a `stopWhen` match or a client tool ends a run the * same way (#29612). So the run must also have used every step in `maxSteps`. * Without a known limit there is nothing to compare against, so no warning. + * A client tool called on the last allowed step still warns: the chunk does not + * say why the loop stopped, only how far it got (#28191 proposes that field). */ export const isMaxStepsFinishChunk = ({ chunk, @@ -60,7 +67,7 @@ export const isMaxStepsFinishChunk = ({ }) => { if (getFinishReason(chunk) !== MAX_STEPS_FINISH_REASON) return false; if (typeof maxSteps !== 'number' || maxSteps < 1) return false; - const usedSteps = countBudgetedSteps(chunk.payload?.output?.steps); + const usedSteps = countBudgetedSteps(chunk.payload?.output); return usedSteps !== undefined && usedSteps >= maxSteps; }; From 192c968689b31c2e0414c9bbbb1263baa1550bb5 Mon Sep 17 00:00:00 2001 From: Leo <108278866+leoisadev1@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:39:05 -0500 Subject: [PATCH 3/4] docs(core): show reading output.stepCount from a thread subscription Co-Authored-By: Claude Opus 5.5 --- .changeset/heavy-files-doubt.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.changeset/heavy-files-doubt.md b/.changeset/heavy-files-doubt.md index 4bdba53b738..e0948ce557d 100644 --- a/.changeset/heavy-files-doubt.md +++ b/.changeset/heavy-files-doubt.md @@ -3,3 +3,13 @@ --- Thread subscription copies of an agent's `finish` chunk now include `output.stepCount`, the number of steps that count against `maxSteps`. These copies leave out `output.steps` to stay small, so subscribers had no way to tell whether a run used its whole step budget. Processor retry steps are not counted, matching how `maxSteps` is enforced. Fixes [#29612](https://github.com/mastra-ai/mastra/issues/29612). + +```ts +const subscription = await agent.subscribeToThread({ threadId, resourceId }) + +for await (const chunk of subscription.stream) { + if (chunk.type === 'finish' && chunk.payload.output.stepCount === maxSteps) { + // The run used its whole step budget + } +} +``` From a2f1013b28ae94eda2f2c8ebba30f0bc9b6be6b9 Mon Sep 17 00:00:00 2001 From: Leo <108278866+leoisadev1@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:45:33 -0500 Subject: [PATCH 4/4] docs(core): guard the stepCount changeset example against a missing count Co-Authored-By: Claude Opus 5.5 --- .changeset/heavy-files-doubt.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.changeset/heavy-files-doubt.md b/.changeset/heavy-files-doubt.md index e0948ce557d..33e7551844e 100644 --- a/.changeset/heavy-files-doubt.md +++ b/.changeset/heavy-files-doubt.md @@ -5,10 +5,12 @@ Thread subscription copies of an agent's `finish` chunk now include `output.stepCount`, the number of steps that count against `maxSteps`. These copies leave out `output.steps` to stay small, so subscribers had no way to tell whether a run used its whole step budget. Processor retry steps are not counted, matching how `maxSteps` is enforced. Fixes [#29612](https://github.com/mastra-ai/mastra/issues/29612). ```ts +const maxSteps = 10 const subscription = await agent.subscribeToThread({ threadId, resourceId }) for await (const chunk of subscription.stream) { - if (chunk.type === 'finish' && chunk.payload.output.stepCount === maxSteps) { + const stepCount = chunk.type === 'finish' ? chunk.payload.output.stepCount : undefined + if (stepCount !== undefined && stepCount >= maxSteps) { // The run used its whole step budget } }