[FEATURE] Stream helper utility for extracting text deltas without 3 levels of nesting

[ErikCH]

Problem Statement

Getting a text delta from agent.stream() requires checking three levels of nesting:

for await (const event of agent.stream(message)) {
  if (
    event.type === 'modelStreamUpdateEvent' &&
    event.event.type === 'modelContentBlockDeltaEvent' &&
    event.event.delta.type === 'textDelta'
  ) {
    res.write(`data: ${JSON.stringify({ type: 'text', content: event.event.delta.text })}\n\n`);
  }
}

Every consumer building a chat UI or SSE endpoint writes this same boilerplate. The Python SDK has a much simpler pattern — "data" in event gives you the text chunk directly.

The official TypeScript streaming docs example (/docs/user-guide/concepts/streaming/async-iterators/) shows JSON.stringify(event) dumping the entire event to the client, which doesn't demonstrate how to selectively extract text for a real chat UI.

Proposed Solution

One or more of:

1. A flattened event type — event.type === 'textDelta' with event.text directly accessible at the top level
2. A utility helper — something like streamTextDeltas(agent.stream(msg)) that yields just the text strings
3. A filter pattern — e.g. agent.stream(msg, { filter: 'text' }) or a .forText() method on the stream

For comparison, the Vercel AI SDK's streamText yields flat events. The Python Strands SDK gives you event["data"] directly.

Use Case

Building an Express.js SSE endpoint (or any HTTP streaming response) for a chat UI where you need to:

• Stream text deltas token-by-token to the frontend
• Show tool call start/end indicators
• Capture metrics from the final agentResultEvent

Currently requires ~15 lines of nested conditionals per event type. A helper could reduce this to 2-3 lines.

Additional Context

• Related (but doesn't solve this): Consider Classes for emitted events sdk-typescript#14 (class-based events, merged), Event Consolidation - Phase 3: Update Type Definitions and Exports sdk-typescript#242 (event consolidation, merged)
• The Python SDK equivalent is "data" in event — one level, no nesting
• AG-UI (chore: allow custom agent name #347) may eventually provide a standard protocol, but a simple utility would help today