Allow consumers to observe document resets on YChat instances

[dlqqq]

Description

Closes #6.

This PR introduces a new observe_chat_reset() method onto MessageRouter, which follows the same interface as observe_chat_init(). Observers added by this method are called whenever the YChat object undergoes a document reset.

• Document resets are performed by re-initializing a YDoc, which purges the YDoc's transaction history. This may be done automatically by the server extension to save memory, or be done in response to an edit made directly to a *.chat file through the filesystem.

Document resets currently only occur when jupyter_server_documents is installed. Observers added to observe_chat_reset() are never fired if jupyter_server_documents is not installed.

Technical details

• jupyter_server_documents (JSD) is not added as a required dependency by this PR. To provide this optional integration with JSD, this branch introduces a new constant JSD_PRESENT = False, which is set to True if jupyter_server_documents is importable.

  • If JSD_PRESENT == False, the extension calls _get_chat_jcollab(), which contains the previous logic for getting a YChat instance from a room ID.

  • If JSD_PRESENT == True, the extension calls _get_chat_jsd(), which calls YRoom.get_jupyter_ydoc(on_reset=...), an API exclusive to JSD. This method automatically attaches an on_reset() observer. This calls MessageRouter._on_chat_reset(), which fires the observers added by MessageRouter.observe_chat_reset() when a YChat reset occurs.

• Due to a bug in JSD, the UI reset & notification only occur after upgrading to jupyterlab_chat==0.18.2.

Testing instructions

• Make sure jupyter_server_documents is not installed by running pip show jupyter_server_documents.

• Start the server and verify that everything works as it had before.

• Run pip install jupyter_server_documents && pip install -U jupyterlab_chat, then restart the server & browser session.

• Open a *.chat file and run touch *.chat in another terminal within JupyterLab. This should trigger a document reset on the chat file, and you should see a notification in the bottom right.

• Open the server logs and verify the following warning was logged:

[W 2025-10-22 15:31:44.146 ServerDocsApp] Out-of-band file change detected. Room ID: 'text:chat:9371d086-1f2c-4711-9639-6541341f88fc', Last detected change: '2025-10-22 22:30:55.393081+00:00', Most recent change: '2025-10-22 22:31:43.933771+00:00'.
[I 2025-10-22 15:31:44.146 ServerDocsApp] Stopping YRoom 'text:chat:9371d086-1f2c-4711-9639-6541341f88fc'.
[W 2025-10-22 15:31:44.147 RouterExtension] Detected `YChat` document reset in room 'text:chat:9371d086-1f2c-4711-9639-6541341f88fc'.

This confirms that the YChat reset was detected by jupyter_ai_router and the appropriate observers would have been called.

[3coins]

@dlqqq
Thanks for looking into this. Looks good, this is going to be useful for other observers as well. Approving and merging.