updated readmes

Author: jiwon-oai

README.md

@@ -36,17 +36,18 @@ You can run the following examples:
   - `show_line_selector` presents the user a multiple-choice question using a widget.
   - Route-planning replies attach entity sources for the stations in the suggested path as annotations.
 
-### Client tool calls that mutate UI state
+### Client tool calls that mutate or fetch UI state
 
 - **Metro Map**:
-  - Client tool `add_station` (sent after the server adds a stop) updates the metro map canvas; handled via `onClientTool` in [ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx).
+  - Client tool `get_selected_stations` pulls the currently selected nodes from the canvas so the agent can use client-side state in its response ([ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx), [metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py)).
 
 ### Fire-and-forget client effects
 
 - **Cat Lounge**:
   - Client effects `update_cat_status` and `cat_say` are invoked by server tools to sync UI state and surface speech bubbles; handled via `onEffect` in [ChatKitPanel.tsx](examples/cat-lounge/frontend/src/components/ChatKitPanel.tsx).
 - **Metro Map**:
   - Client effect `location_select_mode` is streamed within the server action handler ([server.py](examples/metro-map/backend/app/server.py)) after a line is chosen and updates the metro map canvas ([ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx)).
+  - Client effect `add_station` is streamed by the agent after map updates to immediately sync the canvas and focus the newly created stop ([metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py), [ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx)).
 
 ### Page-aware model responses
 
@@ -60,7 +61,12 @@ You can run the following examples:
   - Retrieval tools stream `ProgressUpdateEvent` messages while searching tags, authors, keywords, exact text, or loading the current page so the UI surfaces “Searching…”/“Loading…” states ([news_agent.py](examples/news-guide/backend/app/agents/news_agent.py)).
   - The event finder emits progress as it scans dates, days of week, or keywords to keep users informed during longer lookups ([event_finder_agent.py](examples/news-guide/backend/app/agents/event_finder_agent.py)).
 - **Metro Map**:
-  - The metro agent emits a quick sync update when it loads the line data via `get_map` ([metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py)).
+  - The metro agent emits a progress update while retrieving map information in `get_map`; it also emits a progress update while waiting for a client tool call to complete in `get_selected_stations` ([metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py)).
+
+### Response lifecycle UI state
+
+- **Metro Map**:
+  - The client locks map interaction at response start and unlocks when the stream ends so canvas state doesn’t drift during agent updates by adding `onResponseStart` and `onResponseEnd` handlers ([ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx)).
 
 ### Widgets without actions
 

examples/metro-map/README.md

@@ -13,10 +13,12 @@ Chat-driven GUI updates for a metro map using a React Flow canvas that lets the
 - "Add a new station named Aurora" (line picker widget will appear)
 - "Plan a route from Titan Border to Lyra Verge."
 - "Tell me about @Cinderia station." (@-mention stations; need to type @ manually, copy paste won't work)
+- "Tell me about the stations I've selected." (lasso some stations on the canvas first)
 
 ## Features
 
 - Map sync + lookup tools: `get_map`, `list_lines`, `list_stations`, `get_line_route`, `get_station` keep the agent grounded in the latest network data.
+- Selection-aware replies: the agent calls the `get_selected_stations` client tool to pull the user’s current canvas selection before continuing a response, handled in `onClientTool` ([ChatKitPanel.tsx](frontend/src/components/ChatKitPanel.tsx), [metro_map_agent.py](backend/app/agents/metro_map_agent.py)).
 - Plan-a-route responses attach entity sources for each station in the recommended path so ChatKit can keep the canvas focused on the stops being discussed.
 - Station creation flow: `show_line_selector` streams a clickable `line.select` widget, the server stashes `<LINE_SELECTED>`, and `add_station` triggers a widget update and a client tool call to refresh the canvas and focus the new stop.
 - Location placement helper: after a line is chosen, a `location_select_mode` client effect flips the UI into placement mode so users pick start/end of line for insertion.

examples/metro-map/backend/app/agents/metro_map_agent.py

@@ -274,6 +274,7 @@ async def get_selected_stations(
     ctx: RunContextWrapper[MetroAgentContext],
 ) -> SelectedStationsResult:
     logger.info("[TOOL CALL] get_selected_stations")
+    # This progress update will persist while waiting for the client tool output to be send back to the server.
     await ctx.context.stream(ProgressUpdateEvent(text="Fetching selected stations from the map..."))
     ctx.context.client_tool_call = ClientToolCall(
         name="get_selected_stations",