Improve runtime state views in Positron API (#14825)

Closes #14181

### Summary

Extends the runtime session API on `LanguageRuntimeSession` handles with
three capabilities discussed in #14181.

- **`evaluateCode(..., whenBusy?)`** -- a new optional
`RuntimeBusyBehavior` parameter (`Queue` | `Reject`). `Queue` (default)
preserves today's behavior; `Reject` rejects the evaluation with an
error when the target session is busy instead of queueing it.
- **`getRuntimeState()`** -- a synchronous accessor on
`BaseLanguageRuntimeSession` returning the session's current
`RuntimeState`. Unlike `onDidChangeRuntimeState` (change-only, no
initial value), it can be read at any time to gate work on idleness.
- **`onDidDisconnect` / `onDidReconnect`** -- events on
`BaseLanguageRuntimeSession` that fire when the session's connection to
the underlying runtime drops and is re-established, closing the "silent
reconnect" blind window described in the issue.

The new members are optional on `BaseLanguageRuntimeSession`. They're
implemented on the cross-extension-host session proxy (state and events
forwarded from the main thread via new subscribe/notify RPCs) and on the
real R/Python sessions (`KallichoreSession` is the connection source;
`RSession`/`PythonRuntimeSession` delegate to it).

### Release Notes

#### New Features
- Added a `whenBusy` option to `positron.runtime.evaluateCode`, a
synchronous `getRuntimeState()` accessor, and
`onDidDisconnect`/`onDidReconnect` events on language runtime session
handles (#14181)

#### Bug Fixes
- N/A

### Validation Steps

@:console @:sessions @:reticulate

These are API-surface changes with no UI. Automated coverage:
- **Ext-host API tests** --
`extensions/vscode-api-tests/src/singlefolder-tests/positron/runtime.test.ts`:
`whenBusy=Reject`/`Queue`, `getRuntimeState`, and
`onDidDisconnect`/`onDidReconnect` exposure + firing (fake session).
Run: `./scripts/test-positron-api.sh`
- **Real R (ark) session tests** --
`extensions/positron-r/src/test/runtime-state.test.ts`: live
`getRuntimeState()` Busy->Idle transitions, event exposure, and
`evaluateCode` `whenBusy` Reject/Queue against a real kernel. Run: `npm
run test-extension -- -l positron-r --grep "Runtime state API"`
- **Proxy unit tests** --
`src/vs/workbench/api/test/common/positron/extHostLanguageRuntime.vitest.ts`:
cross-host proxy state seeding, state/disconnect/reconnect forwarding,
and subscribe/unsubscribe lifecycle. Run: `npx vitest run
src/vs/workbench/api/test/common/positron/extHostLanguageRuntime.vitest.ts`

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jmcphers

extensions/positron-python/src/client/positron/session.ts

@@ -82,6 +82,15 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
     /** The emitter for resource usage updates */
     private _resourceUsageEmitter = new vscode.EventEmitter<positron.RuntimeResourceUsage>();
 
+    /** The emitter fired when the connection to the underlying runtime is lost */
+    private _onDidDisconnect = new vscode.EventEmitter<void>();
+
+    /** The emitter fired when the connection to the underlying runtime is re-established */
+    private _onDidReconnect = new vscode.EventEmitter<void>();
+
+    /** Disposables owned by this session (emitters, kernel subscriptions, etc.) */
+    private _disposables: vscode.Disposable[] = [];
+
     /** The Positron Supervisor extension API */
     private adapterApi?: PositronSupervisorApi;
 
@@ -138,6 +147,10 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
 
     onDidUpdateResourceUsage = this._resourceUsageEmitter.event;
 
+    onDidDisconnect = this._onDidDisconnect.event;
+
+    onDidReconnect = this._onDidReconnect.event;
+
     constructor(
         readonly runtimeMetadata: positron.LanguageRuntimeMetadata,
         readonly metadata: positron.RuntimeSessionMetadata,
@@ -170,6 +183,10 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
             await this.onStateChange(state);
         });
 
+        // Ensure the connection state emitters are disposed with the session
+        this._disposables.push(this._onDidDisconnect);
+        this._disposables.push(this._onDidReconnect);
+
         this._installer = this.serviceContainer.get<IInstaller>(IInstaller);
         this._interpreterService = serviceContainer.get<IInterpreterService>(IInterpreterService);
         this._interpreterPathService = serviceContainer.get<IInterpreterPathService>(IInterpreterPathService);
@@ -180,6 +197,15 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
         return this._runtimeInfo;
     }
 
+    /**
+     * Synchronously gets the current runtime state of the session.
+     *
+     * @returns The session's current runtime state.
+     */
+    getRuntimeState(): positron.RuntimeState {
+        return this._state;
+    }
+
     getDynState(): Thenable<positron.LanguageRuntimeDynState> {
         return Promise.resolve(this.dynState);
     }
@@ -819,6 +845,10 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
         if (this._kernel) {
             await this._kernel.dispose();
         }
+
+        // Dispose the connection state emitters and kernel subscriptions
+        this._disposables.forEach((disposable) => disposable.dispose());
+        this._disposables = [];
     }
 
     updateSessionName(sessionName: string): void {
@@ -904,6 +934,21 @@ export class PythonRuntimeSession implements positron.LanguageRuntimeSession, vs
         kernel.onDidUpdateResourceUsage((usage) => {
             this._resourceUsageEmitter.fire(usage);
         });
+
+        // Forward the kernel's connection state changes, if it supports them.
+        const disconnectListener = kernel.onDidDisconnect?.(() => {
+            this._onDidDisconnect.fire();
+        });
+        if (disconnectListener) {
+            this._disposables.push(disconnectListener);
+        }
+        const reconnectListener = kernel.onDidReconnect?.(() => {
+            this._onDidReconnect.fire();
+        });
+        if (reconnectListener) {
+            this._disposables.push(reconnectListener);
+        }
+
         return kernel;
     }
 

extensions/positron-r/src/session.ts

@@ -112,6 +112,12 @@ export class RSession implements positron.LanguageRuntimeSession, vscode.Disposa
 	private _resourceUsageEmitter =
 		new vscode.EventEmitter<positron.RuntimeResourceUsage>();
 
+	/** The emitter fired when the connection to the underlying runtime is lost */
+	private _onDidDisconnect = new vscode.EventEmitter<void>();
+
+	/** The emitter fired when the connection to the underlying runtime is re-established */
+	private _onDidReconnect = new vscode.EventEmitter<void>();
+
 	/** The Positron Supervisor extension API */
 	private adapterApi?: PositronSupervisorApi;
 
@@ -162,6 +168,12 @@ export class RSession implements positron.LanguageRuntimeSession, vscode.Disposa
 		this.onDidChangeRuntimeState = this._stateEmitter.event;
 		this.onDidEndSession = this._exitEmitter.event;
 		this.onDidUpdateResourceUsage = this._resourceUsageEmitter.event;
+		this.onDidDisconnect = this._onDidDisconnect.event;
+		this.onDidReconnect = this._onDidReconnect.event;
+
+		// Ensure the emitters are disposed when the session is disposed
+		this._disposables.push(this._onDidDisconnect);
+		this._disposables.push(this._onDidReconnect);
 
 		// Timestamp the session creation
 		this._created = Date.now();
@@ -178,6 +190,8 @@ export class RSession implements positron.LanguageRuntimeSession, vscode.Disposa
 	onDidReceiveRuntimeMessage: vscode.Event<positron.LanguageRuntimeMessage>;
 	onDidChangeRuntimeState: vscode.Event<positron.RuntimeState>;
 	onDidUpdateResourceUsage: vscode.Event<positron.RuntimeResourceUsage>;
+	onDidDisconnect: vscode.Event<void>;
+	onDidReconnect: vscode.Event<void>;
 
 	/**
 	 * Accessor for the current state of the runtime.
@@ -186,6 +200,15 @@ export class RSession implements positron.LanguageRuntimeSession, vscode.Disposa
 		return this._state;
 	}
 
+	/**
+	 * Synchronously gets the current runtime state of the session.
+	 *
+	 * @returns The session's current runtime state.
+	 */
+	getRuntimeState(): positron.RuntimeState {
+		return this._state;
+	}
+
 	/**
 	 * Accessor for the creation time of the runtime.
 	 */
@@ -836,6 +859,20 @@ export class RSession implements positron.LanguageRuntimeSession, vscode.Disposa
 			this._resourceUsageEmitter.fire(usage);
 		});
 
+		// Forward the kernel's connection state changes, if it supports them.
+		const disconnectListener = kernel.onDidDisconnect?.(() => {
+			this._onDidDisconnect.fire();
+		});
+		if (disconnectListener) {
+			this._disposables.push(disconnectListener);
+		}
+		const reconnectListener = kernel.onDidReconnect?.(() => {
+			this._onDidReconnect.fire();
+		});
+		if (reconnectListener) {
+			this._disposables.push(reconnectListener);
+		}
+
 		return kernel;
 	}
 

extensions/positron-r/src/test/runtime-state.test.ts

@@ -0,0 +1,157 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (C) 2026 Posit Software, PBC. All rights reserved.
+ *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import './mocha-setup';
+
+import * as positron from 'positron';
+import * as vscode from 'vscode';
+import * as assert from 'assert';
+import * as testKit from './kit';
+import { RSession } from '../session';
+import { delay } from '../util';
+
+/**
+ * Exercises the improved runtime-state API surface against a real R (ark)
+ * session: the synchronous `getRuntimeState()` accessor, the
+ * `onDidDisconnect`/`onDidReconnect` events, and the `evaluateCode` `whenBusy`
+ * behavior.
+ */
+suite('Runtime state API', () => {
+	let session: RSession;
+	let sesDisposable: vscode.Disposable;
+
+	suiteSetup(async () => {
+		const [ses, disposable] = await testKit.startR('Suite: Runtime state API');
+		session = ses;
+		sesDisposable = disposable;
+	});
+
+	suiteTeardown(async () => {
+		if (sesDisposable) {
+			await sesDisposable.dispose();
+		}
+	});
+
+	test('getRuntimeState is exposed and reports the live state', async () => {
+		// Fetch the session through the public API, the same way an external
+		// extension would.
+		const handle = await positron.runtime.getSession(session.metadata.sessionId);
+		assert.ok(handle, 'the session should be retrievable via getSession');
+		assert.strictEqual(typeof handle.getRuntimeState, 'function',
+			'getRuntimeState should be exposed on the session handle');
+
+		// After startup the session should settle into an idle-ish state.
+		await testKit.pollForSuccess(() => {
+			const state = handle.getRuntimeState!();
+			assert.ok(
+				state === positron.RuntimeState.Idle || state === positron.RuntimeState.Ready,
+				`expected idle/ready after startup, got '${state}'`);
+		});
+
+		// The public handle and the underlying RSession should agree.
+		assert.strictEqual(handle.getRuntimeState!(), session.getRuntimeState(),
+			'the API handle and the underlying session should report the same state');
+	});
+
+	test('getRuntimeState transitions to Busy during execution and back to Idle', async () => {
+		const handle = await positron.runtime.getSession(session.metadata.sessionId);
+		assert.ok(handle);
+
+		// Ensure we start idle.
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(handle.getRuntimeState!(), positron.RuntimeState.Idle);
+		});
+
+		// Kick off a long-running computation without awaiting it.
+		positron.runtime.executeCode('r', 'Sys.sleep(2)', false, false).then(() => { }, () => { });
+
+		// The state should become Busy.
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(handle.getRuntimeState!(), positron.RuntimeState.Busy,
+				'session should report Busy while executing');
+		});
+
+		// And return to Idle once the computation completes.
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(handle.getRuntimeState!(), positron.RuntimeState.Idle,
+				'session should return to Idle after executing');
+		}, 50, 10000);
+	});
+
+	test('onDidDisconnect and onDidReconnect are exposed on the handle', async () => {
+		const handle = await positron.runtime.getSession(session.metadata.sessionId);
+		assert.ok(handle);
+
+		assert.strictEqual(typeof handle.onDidDisconnect, 'function',
+			'onDidDisconnect should be exposed on the session handle');
+		assert.strictEqual(typeof handle.onDidReconnect, 'function',
+			'onDidReconnect should be exposed on the session handle');
+
+		// Subscribing must not throw, and the events must not fire spuriously
+		// while the session is healthy.
+		let disconnected = false;
+		const sub = handle.onDidDisconnect!(() => { disconnected = true; });
+		await delay(200);
+		sub.dispose();
+		assert.strictEqual(disconnected, false,
+			'onDidDisconnect should not fire while the session is connected');
+	});
+
+	test('evaluateCode with whenBusy=Reject rejects while the session is busy', async () => {
+		const sessionId = session.metadata.sessionId;
+
+		// Ensure the session is idle before we begin.
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(session.getRuntimeState(), positron.RuntimeState.Idle);
+		});
+
+		// Make the session busy with a long-running computation.
+		positron.runtime.executeCode('r', 'Sys.sleep(3)', false, false).then(() => { }, () => { });
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(session.getRuntimeState(), positron.RuntimeState.Busy);
+		});
+
+		// Reject behavior should throw while busy.
+		let rejected = false;
+		let message = '';
+		try {
+			await positron.runtime.evaluateCode('r', '1 + 1', undefined, sessionId,
+				positron.RuntimeBusyBehavior.Reject);
+		} catch (err: any) {
+			rejected = true;
+			message = err?.message ?? String(err);
+		}
+		assert.ok(rejected, 'evaluateCode should reject when the session is busy and whenBusy is Reject');
+		assert.ok(/busy/.test(message), `the rejection should mention busy, got: ${message}`);
+
+		// Wait for the session to become idle again before finishing.
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(session.getRuntimeState(), positron.RuntimeState.Idle);
+		}, 50, 10000);
+	});
+
+	test('evaluateCode with whenBusy=Queue resolves once the session is idle', async () => {
+		const sessionId = session.metadata.sessionId;
+
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(session.getRuntimeState(), positron.RuntimeState.Idle);
+		});
+
+		// Make the session busy briefly.
+		positron.runtime.executeCode('r', 'Sys.sleep(1)', false, false).then(() => { }, () => { });
+		await testKit.pollForSuccess(() => {
+			assert.strictEqual(session.getRuntimeState(), positron.RuntimeState.Busy);
+		});
+
+		// Queue an evaluation while busy; it should not reject, and should
+		// eventually resolve with the result once the session is idle again.
+		const result = await positron.runtime.evaluateCode('r', '2 + 3', undefined, sessionId,
+			positron.RuntimeBusyBehavior.Queue);
+
+		// The queued evaluation should have run and produced 5.
+		const serialized = JSON.stringify(result);
+		assert.ok(/5/.test(serialized), `queued evaluation should return 5, got: ${serialized}`);
+	});
+});