TS streaming events

[mkmeral]

Validate this issue, fix it, and create a PR on TS repo, and tag me. (make sure to read agents.md)

# TypeScript SDK: Wire-Safe Streaming Events

## Problem

Every event from `agent.stream()` carries `agent: LocalAgent` — the full Agent instance with conversation history, app state, model config, and internal registries. `JSON.stringify(event)` doesn't crash, but it's bloated:

| Conversation size | Per-event JSON | Should be |
|---|---|---|
| 100 messages | ~54 KB | ~100-200 bytes |
| 1,000 messages | ~246 KB | ~100-200 bytes |

## Fix

Add `toJSON()` to every event class. `JSON.stringify` calls it automatically. Zero API changes — `event.agent` still works for direct access.

## What `stream()` Yields (in order)

```
BeforeInvocationEvent
MessageAddedEvent              ← user message appended
BeforeModelCallEvent
ModelStreamUpdateEvent (×N)    ← token deltas (bulk of events)
ContentBlockEvent (×N)         ← completed blocks (text, tool_use, reasoning)
ModelMessageEvent              ← full message + stopReason
AfterModelCallEvent
BeforeToolsEvent
BeforeToolCallEvent
ToolStreamUpdateEvent (×N)     ← tool progress events
AfterToolCallEvent
ToolResultEvent
AfterToolsEvent
MessageAddedEvent (×2)         ← assistant + tool result messages
  ── loop repeats if LLM requests more tools ──
ModelStreamUpdateEvent (×N)    ← final answer tokens
ContentBlockEvent
ModelMessageEvent
AfterModelCallEvent
MessageAddedEvent
AfterInvocationEvent
AgentResultEvent               ← final result
```

## Event-by-Event: What to Keep, What to Exclude

**Excluded from ALL events:** `agent: LocalAgent`

| Event | Keep | Exclude (besides `agent`) | `toJSON()` |
|---|---|---|---|
| `ModelStreamUpdateEvent` | `event: ModelStreamEvent` | | `{ type, event }` |
| `ContentBlockEvent` | `contentBlock` | | `{ type, contentBlock }` |
| `ModelMessageEvent` | `message`, `stopReason` | | `{ type, message, stopReason }` |
| `ToolResultEvent` | `result: ToolResultBlock` | | `{ type, result }` |
| `ToolStreamUpdateEvent` | `event: ToolStreamEvent` | | `{ type, event }` |
| `AgentResultEvent` | `result: AgentResult` | | `{ type, result }` |
| `MessageAddedEvent` | `message` | | `{ type, message }` |
| `BeforeToolCallEvent` | `toolUse: {name,id,input}` | `tool: Tool` (class w/ methods), `cancel` (mutable state) | `{ type, toolUse }` |
| `AfterToolCallEvent` | `toolUse`, `result` | `tool: Tool`, `error` → `.message`, `retry` (mutable state) | `{ type, toolUse, result, error? }` |
| `AfterModelCallEvent` | `stopData?` | `error` → `.message` | `{ type, stopData?, error? }` |
| `BeforeToolsEvent` | `message` | `cancel` (mutable state) | `{ type, message }` |
| `AfterToolsEvent` | `message` | | `{ type, message }` |
| `BeforeInvocationEvent` | *(nothing)* | | `{ type }` |
| `AfterInvocationEvent` | *(nothing)* | | `{ type }` |
| `BeforeModelCallEvent` | *(nothing)* | | `{ type }` |
| `InitializedEvent` | *(nothing)* | | `{ type }` |

All the "keep" fields are already serializable: `Message`, `ContentBlock`, `ToolResultBlock`, `AgentResult` have `toJSON()`. `ModelStreamEvent` and `ToolStreamEvent` are plain data. `StopReason` is a string. `toolUse` is `{ name: string, toolUseId: string, input: JSONValue }`.

## Before / After

```typescript
for await (const event of agent.stream('Hello')) {
  res.write(`data: ${JSON.stringify(event)}\n\n`)
}
```

Same code. Before: ~54KB per text delta (entire agent serialized). After: ~120 bytes (just the delta).

[agent-of-mkmeral]

✅ Validated and implemented

PR created: strands-agents/sdk-typescript#708

Validation summary

I validated the issue against the actual TypeScript SDK codebase:

1. Confirmed: All 16 event classes in src/hooks/events.ts carry agent: LocalAgent with no toJSON() override
2. Confirmed: LocalAgent interface includes messages: Message[], appState: StateStore, and toolRegistry: ToolRegistry — all of which serialize recursively
3. Confirmed: The data fields (Message, ContentBlock, ToolResultBlock, AgentResult, ModelStreamEvent, ToolStreamEvent) already have toJSON() or are plain data
4. Confirmed: Zero API changes needed — toJSON() is called automatically by JSON.stringify()

What the PR does

Adds toJSON() to all 16 event classes:

• Lifecycle events (InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, BeforeModelCallEvent) → { type }
• Data events (ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, etc.) → { type, ...payload }
• Tool events → exclude tool: Tool (class with methods) and mutable flags (cancel, retry)
• Error events → convert Error to .message string

Quality gates

• ✅ 1705/1705 unit tests pass (including 19 new toJSON tests)
• ✅ TypeScript type-check passes
• ✅ ESLint passes
• ✅ Prettier format check passes

cc @mkmeral

[mkmeral]

strands-agents/sdk-typescript#708 (comment)

[agent-of-mkmeral]

✅ Review feedback addressed

Applied @zastrowm's requested change on PR #708:

Change: Replaced all inline type literals with Pick<EventClass, 'field'> for toJSON() return types. This keeps the wire types automatically in sync with the class definitions.

Examples

// Before (inline literal)
toJSON(): { type: 'modelStreamUpdateEvent'; event: ModelStreamEvent } { ... }

// After (Pick<>)
toJSON(): Pick<ModelStreamUpdateEvent, 'type' | 'event'> { ... }

// Error-transforming events use intersection
toJSON(): Pick<AfterToolCallEvent, 'type' | 'toolUse' | 'result'> & { error?: string } { ... }

Quality gates

• ✅ 1705/1705 tests pass
• ✅ TypeScript type-check passes
• ✅ ESLint passes
• ✅ Prettier passes

cc @mkmeral