# Stream messages, tools, and results

Observe the entire execution as it happens, with durable state and reconnect behavior included.

## What streams

An execution can produce messages, tool calls, tool results, backend invocations, progress, usage, and requests for input. A completed message does not mean the run has completed. Tool arguments arrive at the granularity supplied by the service. The API does not invent argument-token chunks.

Tool records and backend invocation records have separate identities. One tool can make several backend requests. A tool built into the execution environment can have no backend invocation. Do not join their IDs or infer exactly-once business side effects.

## Observe updates

### Python

The high-level Python stream hydrates a coherent snapshot, applies ordered events, ignores duplicates, and restores state when a prerequisite is missing. Replace your view when `SnapshotUpdate` arrives.

```python
from wkala import SnapshotUpdate, ToolUpdated, MCPInvocationUpdated

async with run.stream() as stream:
    async for update in stream:
        if isinstance(update, SnapshotUpdate):
            print(stream.state.runs[run.id].status)
        elif isinstance(update, ToolUpdated):
            tool = update.data.tool
            print(tool.title, tool.status)
            print(tool.arguments, tool.output, tool.content)
        elif isinstance(update, MCPInvocationUpdated):
            call = update.data.invocation
            print(call.server_name, call.status, call.result)
```


### TypeScript

Use the TypeScript store from `run.stream()` or React `useSession()` for a coherent snapshot, ordered updates, duplicate handling, and recovery. `run.events()` below is a lower-level iterator. It validates sequence and can raise `RecoveryRequired` on a gap. Fetch a new snapshot instead of continuing from incomplete state.

```typescript
const observer = new AbortController()
for await (const event of run.events({ signal: observer.signal })) {
  switch (event.type) {
    case "message.delta":
      console.log(event.data.message_id, event.data.part_id, event.data.delta)
      break
    case "tool.updated":
      console.log(event.data.tool)
      break
    case "mcp.invocation.updated":
      console.log(event.data.invocation.result)
      break
    case "interaction.updated":
      console.log(event.data.interaction)
      break
    case "run.updated":
      console.log(event.data.run.status, event.data.run.usage)
      break
  }
}
```


Authoritative `tool.updated` and `message.updated` records replace earlier versions of the same record. Results preserve typed JSON, including arrays, scalars, and MCP `structuredContent` or `isError`. Rich message content may include text, embedded image or audio, resources, and resource links. Render unsupported content explicitly. Do not automatically fetch arbitrary resource links.

## Observation and execution are independent

Closing a stream, unmounting a component, or losing a browser connection stops observation. An admitted run continues. Request cancellation explicitly when you mean to stop execution:

### Python

```python
await run.cancel()
```


### TypeScript

```typescript
await run.cancel()
```


A run-scoped iterator ends after its terminal event. Observe the session or request a later snapshot to see subsequent reconciliation of an uncertain backend operation. `tool.incomplete` or an invocation with `uncertain` status requires application reconciliation.

## Proxy behavior

Use the supplied [Next proxy](/docs/raw/nextjs?locale=en) and [customer backend example](/docs/raw/python-backend?locale=en) to retain authentication and ownership. The supplied example uses a Python backend. A proxy must forward response headers before consuming the body. It must disable event buffering and leave the body open for the lifetime of observation. A connection timeout may bound opening the response. It must not truncate a healthy long-running stream.

An SDK stream is not a generic chatbot token response. Sessions, durable runs, tools, permissions, and usage are independent parts of the same execution state.
