Support session init hooks (mostly motivated by R)

[jennybc]

Addresses #9763
Addresses posit-dev/ark#697

Requires this companion PR in ark: posit-dev/ark#1088

Summary

Adds infrastructure for R session init hooks that fire after the frontend is fully connected to the runtime. This enables a user or admin to store code in .Rprofile that drives the UI or requires two-way communication with the frontend.

Two main changes:

1. comm_open data carries { console_width, start_type } when the UI comm opens. The runtime uses console_width immediately (no separate RPC needed). start_type is informational/logging. (This is not load-bearing for session init hooks. Rather, it's a little goodie I kept from my second approach to this problem. We had hoped to fire session init hooks during UI comm opening, but it just doesn't work. It's too early. But this does feel like the right way to inform the backend of the initial console width.)

2. frontend_ready RPC is sent after comm_open succeeds. The runtime uses this signal to fire session hooks. This is a separate step from comm_open because the hooks may need to make RPCs back to the frontend, which requires the comm to be fully registered first. (This is basically a return to my first approach to the problem. Even more work was required in ark and is described in that PR.)

Start type mapping

RuntimeStartMode is an internal Positron enum. start_type is the external value sent to the runtime via the frontend_ready RPC, which the runtime uses to decide which hooks to fire.

RuntimeStartMode (Positron internal)	start_type (runtime-facing)	When
Starting	"new"	New runtime session, in a new or existing IDE session
Switching	"new"	Notebook switches to a different kernel
Restarting	"restart"	Existing runtime session restarted within an IDE session
Reconnecting	"reconnect"	Frontend reconnects to an existing runtime session (e.g. window reload, resuming a session on Workbench)

Changes

• ui-backend-openrpc.json: Added frontend_ready RPC with start_type param. Ran codegen (npx tsx generate-comms.ts ui), which updated positronUiComm.ts, ui_comm.py, and ui_comm.rs (in ark).
• languageRuntimeUiClient.ts: Added frontendReady() wrapper on UiClientInstance (the generated method lives on PositronUiComm but callers go through UiClientInstance).
• activeRuntimeSession.ts: Tracks startMode on ActiveRuntimeSession. New getStartType() maps it to runtime-facing values. startUiClientImpl() passes { console_width, start_type } in comm_open data (previously {}). Sends frontendReady(startType) after comm setup completes.
• runtimeSession.ts: Threads startMode through attachToSession() and updates it when a restart is detected.
• positron-r/session.ts: Removed setConsoleWidth() (now handled via comm_open data on the ark side).

Background

This enables runtime-side session init hooks, inspired by RStudio's rstudio.sessionInit. See the ark companion PR for the runtime-side implementation. Relevant docs re: RStudio:

• https://rstudio.github.io/rstudioapi/articles/r-session.html#running-at-startup
• https://docs.posit.co/ide/server-pro/admin/rstudio_pro_sessions/session_startup_scripts.html

What sorts of things do people do in rstudio.sessionInit? Special thanks to @jthomasmock for helping gather this list. It's worth noting that session init hooks are much more relevant in a Workbench/enterprise context than desktop/individual user.

• Use rstudioapi to do something that drives the UI, such as rstudioapi::navigateToFile(). This has been my main manual test case. However, since it's "fire and forget", it can't be the only test case.
• Use rstudioapi to trigger two-way communication with the UI, such as rstudioapi::getActiveProject(). This turns out to be a very important use case to test.
• Emit a welcome message that is correctly formatted for the actual console width (versus a default of 80). Console width is not recognized at R session startup r-lib/cli#578
• Display a legal compliance message to users in new sessions.
• Reinstall R packages, e.g. via renv::restore(), after an OS upgrade. Note that the hook itself does not detect the OS upgrade. But if the upgrade has been detected, the hook gets registered. This example is from Posit Cloud.
• Defer package load that was conflicting with other startup events (package installation). This example is from RStudio itself. IDE keeps getting stuck in a loop to restart R when trying to install a package that is already installed rstudio/rstudio#2656
• Switch the RStudio theme (light vs. dark) based on the time of day. From rsthemes recommended usage. Use rstudio.sessionInit hook instead of later gadenbuie/rsthemes#8
• Automatically load sparklyr and establish a Spark connection to a YARN cluster.
• Append an internal package repository or library path in a way that absolutely can't be clobbered by RStudio itself.

Release Notes

New Features

• positron.session_init and positron.session_reconnect are new hooks that are executed in the R session, once R startup is complete and Positron is fully operational and able to handle requests that pertain to the UI, such as rstudioapi calls. This duo is intended to be analogous to RStudio's rstudio.sessionInit. A positron.session_init hook function should accept a start_type parameter, with possible values "new" or "restart". A positron.session_reconnect hook takes no input.

Bug Fixes

• N/A

QA Notes

Temporarily make this your .Rprofile (requires ark built from companion PR) and make sure the current folder has a DESCRIPTION file.

Click to expand

message("Plain message, before session init hooks are defined")
message("cli thinks the width is ", cli::console_width())

setHook(
  "positron.session_init",
  function(start_type) {
    message(
      "positron.session_init called with `start_type = '",
      start_type,
      "'`"
    )
    message("cli thinks the width is ", cli::console_width())

    switch(
      start_type,
      new = message("Welcome to Positron ", rstudioapi::getVersion()),
      restart = message(
        "Welcome BACK to Positron ",
        rstudioapi::getVersion()
      ),
      message("Unknown start_type: ", start_type)
    )

    open_this <- "DESCRIPTION"
    if (file.exists(open_this)) {
      message("Opening '", open_this, "'")
      rstudioapi::navigateToFile(open_this)
    }

    message("Active project: ", rstudioapi::getActiveProject())
  },
  action = "append"
)

setHook(
  "positron.session_reconnect",
  function(...) {
    message("Reconnected to Positron ", rstudioapi::getVersion())
    message("Active project: ", rstudioapi::getActiveProject())
    message("cli thinks the width is ", cli::console_width())
  },
  action = "append"
)

message("Another plain message, after session init hooks are defined")

In each case, DESCRIPTION should be opened in the editor via rstudioapi::navigateToFile(). Here's what you should see in the Console, up to whatever your console width and active project are.

New session (start_type = "new"):

Plain message, before session init hooks are defined
cli thinks the width is 80
Another plain message, after session init hooks are defined
positron.session_init called with `start_type = 'new'`
cli thinks the width is 148
Welcome to Positron 2026.4.0
Opening 'DESCRIPTION'
Active project: /Users/jenny/work/readr

Restart R (start_type = "restart"):

Plain message, before session init hooks are defined
cli thinks the width is 80
Another plain message, after session init hooks are defined
positron.session_init called with `start_type = 'restart'`
cli thinks the width is 148
Welcome BACK to Positron 2026.4.0
Opening 'DESCRIPTION'
Active project: /Users/jenny/work/readr

Reload window (start_type = "reconnect"):

Notice that only the hook is being run, not the top-level .Rprofile statements.

Reconnected to Positron 2026.4.0
Active project: /Users/jenny/work/readr
cli thinks the width is 148

TODOs:

• Why .Rprofile messages so red? message() output during R startup appears red in Positron console ark#1101
• Why can't you do readline() or menu() in a session init hook? menu() and readline() don't work in positron session init hooks ark#1130
• Consider E2E tests. E2E test for R session init hooks #12802
• Documentation. Open an issue for this.

[github-actions]

E2E Tests 🚀
This PR will run tests tagged with: @:critical

^{readme  valid tags}

[jmcphers]

This looks and works great for me. I'm seeing all 3 start types (new, restart, reconnect) fire correctly, and verified that console width is still getting tracked correctly at attach and resize.