Browser view does not auto-refresh when catalog entry is updated via MCP

[paddymul]

Summary

When a catalog entry is updated through xorq MCP tools (join, filter, mutate, select), the Buckaroo browser view does not reliably auto-refresh to show the new data. The user has to either manually refresh the browser or the agent has to call xorq_view_build again.

Reproduction

1. Open a catalog entry in the Buckaroo browser viewer
2. From Claude Code, call xorq_join or xorq_filter on that entry (creating a new revision)
3. Look at the browser — it still shows the old revision

Expected behavior

When a catalog entry gets a new revision, the browser view should either:

• Auto-refresh to show the latest revision, OR
• Show a visual indicator that the data is stale (e.g., a banner: "New revision available — click to refresh")

Context

During a demo session, the user said "I don't see that" after a join was completed, and had multiple moments of confusion looking at stale data ("I don't see first and last name... wait, no, there it is now"). The agent had to call xorq_view_build again to re-trigger the browser render.

In a live demo context this is particularly painful — the presenter looks at the screen, doesn't see the expected update, loses confidence, and has to verbally backtrack. This is the #1 demo-killer observed.

Possible approaches

• WebSocket push from the xorq MCP web server when a catalog entry is updated
• Polling the catalog revision on a short interval (e.g., every 2s)
• At minimum, the xorq_filter/xorq_join/xorq_mutate/xorq_select MCP tools could call xorq_view_build automatically after updating

[paddymul]

Implementation Plan

Overview

Add auto-refresh to the browser view when catalog entries are updated via MCP.

Steps

1. Server-side: Add a change-notification endpoint — e.g. /catalog/updates using Server-Sent Events (SSE) or a simple polling endpoint that returns a version/timestamp counter. Increment on every view_data or catalog mutation call.

2. Client-side: Poll or listen for changes — in the standalone HTML/JS view:

   • Option A (simple): setInterval polling /catalog/updates every 2-3 seconds, refresh data if version changed
   • Option B (better): SSE EventSource connection, re-fetch data on event
   • On change detected, re-fetch the table data and re-render the AG Grid

3. Debounce rapid updates — if multiple catalog mutations happen in quick succession, batch the refresh to avoid thrashing.

4. Test — MCP integration test: update a catalog entry, verify the browser endpoint serves the new data within the polling interval.

Files to modify

• buckaroo/server/ — add change notification endpoint
• packages/buckaroo-js-core/public/ or standalone HTML template — add polling/SSE client
• buckaroo/mcp_tool.py — increment version counter on mutations

@codex

[chatgpt-codex-connector]

Summary

• Added session-level change tracking (data_version, data_updated_at) plus a bump_data_version() helper so the server can signal when session data has been replaced. buckaroo/server/session.pyL37-L40 buckaroo/server/session.pyL182-L189
• Updated both /load and /load_compare flows to increment the session version counter whenever new data is loaded into an existing session. buckaroo/server/handlers.pyL244-L249 buckaroo/server/handlers.pyL406-L417
• Added a new GET /session_updates/{session_id} endpoint and registered it in the Tornado app routing. buckaroo/server/handlers.pyL457-L471 buckaroo/server/app.pyL6-L27
• Added client-side polling in the standalone session HTML that checks /session_updates/{session} every 2s and triggers a debounced page reload when a newer version is detected. buckaroo/server/handlers.pyL518-L560
• Added Playwright coverage for the new updates endpoint (data_version increments and unknown-session 404 behavior). packages/buckaroo-js-core/pw-tests/server.spec.tsL512-L552

Testing

• ❌ pnpm --dir packages/buckaroo-js-core test:server -- server.spec.ts -g "session_updates API|health endpoint returns ok" (failed because the test web server could not start in this environment: missing buckaroo/static/widget.js at runtime).
• ⚠️ pytest -q buckaroo/server -k session (no matching tests were present under that path, so nothing executed).
• ✅ python -m compileall buckaroo/server/handlers.py buckaroo/server/app.py buckaroo/server/session.py

Committed on the current branch and created the follow-up PR via make_pr with title: “Follow-up: auto-refresh standalone browser view on session data changes”.

View task →

[paddymul]

Related: PRs #568, #578, #593

• PR feat: per-request no_browser in /load POST body #568 (merged): per-request no_browser in /load POST body — improved server request handling
• PR fix: MCP + server reliability, observability, and hardening #578 (merged): MCP + server reliability, observability, and hardening
• PR feat: add /load_compare endpoint for col_join_dfs diff styling #593 (merged): Added /load_compare endpoint — extends server capabilities

The auto-refresh mechanism itself is not yet implemented. The server infrastructure is more robust now, making it easier to add the change-notification endpoint described in the plan above.