Events

---
description: The PyWry event system — namespaced events, request/response round-trips, widget IDs, component IDs, and how tool results flow back to the agent.
---

# PyWry Event System — Agent Reference

> **The event bus is the plumbing underneath every MCP tool.**  You
> rarely need to think about it — the typed tools wrap emit + wait +
> state-poll for you — but when you reach for `send_event` or
> interpret tool results, this is how it works.

## Event names are namespaced

Every event has the form `namespace:event-name`, e.g.:

- `tvchart:symbol-search`     — ask the chart to open symbol search
- `tvchart:state-response`    — chart's reply with its current state
- `tvchart:data-request`      — chart asks Python for bars
- `tvchart:data-response`     — Python delivers bars
- `toolbar:request-state`     — ask a toolbar component for its value
- `toolbar:state-response`    — component's reply
- `chat:user-message`         — user typed something
- `chat:ai-response`          — model produced a token
- `pywry:update-theme`        — dark/light mode change

Never emit an event with a name that doesn't match `namespace:event-name`
— the framework rejects it.

## Widget IDs vs component IDs

**widget_id** — identifies the top-level PyWry widget (a chart, a grid,
a chat panel, a dashboard).  Every MCP tool takes `widget_id` as an
argument because all events route to the widget first.

**componentId** — identifies a child *inside* a widget (a specific
toolbar button, a marquee ticker slot, a chart pane).  Component IDs
are scoped to their containing widget.

When you call `send_event(widget_id, event_type, data)`, the
`widget_id` picks the target widget; anything identifying a specific
component goes in the `data` payload (typically as `data.componentId`
or `data.chartId`).

## Request / response pattern

Some events are fire-and-forget (e.g. `tvchart:symbol-search` —
"please do this").  Others are request/response round-trips where the
caller wants a reply (e.g. `tvchart:request-state` → `tvchart:state-response`).

The framework correlates request/response with a `context` token:

1. Emitter generates a random `context` token.
2. Emitter injects it into the request payload.
3. Listener sees the request, attaches the same `context` to its
   response, and emits the response event.
4. Emitter sees the matching `context` on the response and wakes up.

All of this is handled inside `request_response()` in
`pywry.mcp.state` — you never construct tokens yourself.  Typed MCP
tools that need a reply (`tvchart_request_state`,
`tvchart_list_indicators`) use this under the hood and return the
stripped response (no `context` token) in their tool result.

## How tool results reach the agent

```
Agent             MCP Server          PyWry Widget (JS)
  │                   │                       │
  │ tool call ──────► │                       │
  │                   │ widget.emit() ──────► │
  │                   │                       │ (updates chart)
  │                   │                       │
  │                   │ ◄───── bridge.emit()  │
  │                   │ (state-response)      │
  │                   │                       │
  │ ◄──── tool result │                       │
  │ (includes state)  │                       │
```

Mutating tools (`tvchart_symbol_search`, `tvchart_change_interval`)
poll `tvchart:request-state` after emitting the mutation, wait for the
chart to actually reflect the change, and return the real post-change
state in the tool result.  The `state` field in the tool result
contains the SAME structure as a direct call to
`tvchart_request_state`.

If the mutation didn't settle in time, the result contains a `note`
field explaining the discrepancy — relay the note to the user, do
not invent state.

## Emitting events from tools — `send_event`

Only reach for `send_event` when no typed MCP tool exists for the
target event.  It's a raw passthrough with no state polling:

```
send_event(widget_id, event_type, data)
  → { "widget_id": ..., "event_sent": true, "event_type": ... }
```

Example — apply a rare tvchart option with no typed wrapper:

```
send_event(
  widget_id="chart",
  event_type="tvchart:apply-options",
  data={"chartOptions": {"timeScale": {"secondsVisible": False}}},
)
```

The returned `event_sent: true` means the event was successfully
handed to the widget — it does NOT mean the JS handler ran
successfully.  For confirmation, follow up with
`tvchart_request_state` to read the new state.

## Event capture (`get_events`)

Some events fire from the widget *to* Python (e.g. the user clicked a
bar, moved the crosshair).  These are automatically captured into a
per-widget event buffer and can be retrieved with:

```
get_events(widget_id, event_types=[...], clear=True)
  → { "events": [{ "event_type": ..., "data": ..., "label": ... }, ...] }
```

Default captured events for charts:

- `tvchart:click`
- `tvchart:crosshair-move`
- `tvchart:visible-range-change`
- `tvchart:drawing-added`
- `tvchart:drawing-deleted`
- `tvchart:open-layout-request`
- `tvchart:interval-change`
- `tvchart:chart-type-change`

Use `get_events` if the user asks "what did I just click" or "what
was the last drawing I added".

## Don'ts

- Do NOT synthesise event payloads.  Only report event data the
  framework actually handed you.
- Do NOT emit events whose name doesn't match `ns:name` — they're
  rejected.
- Do NOT emit to a widget id that isn't registered — the tool will
  return an error listing the registered widgets; correct and retry.
- Do NOT assume `event_sent: true` means the downstream JS succeeded.
  When it matters, follow up with `tvchart_request_state` (or the
  relevant state query) to confirm.