Merged PR posit-dev/positron-python#221: Provide a reason for runtime exits

Merge pull request #221 from posit-dev/feature/runtime-exit-reason

Provide a reason for runtime exits
--------------------
Commit message for posit-dev/positron-python@e603579:

provide a reason for runtime exits


Authored-by: Jonathan McPherson <[email protected]>
Signed-off-by: Jonathan McPherson <[email protected]>

Author: jmcphers

extensions/positron-python/positron-dts/positron.d.ts

@@ -126,6 +126,53 @@ declare module 'positron' {
 		Continue = 'continue',
 	}
 
+	/**
+	 * Possible reasons a language runtime could exit.
+	 */
+	export enum RuntimeExitReason {
+		/** The runtime exited because it could not start correctly. */
+		StartupFailed = 'startupFailed',
+
+		/** The runtime is shutting down at the request of the user. */
+		Shutdown = 'shutdown',
+
+		/** The runtime exited because it was forced to quit. */
+		ForcedQuit = 'forcedQuit',
+
+		/** The runtime is exiting in order to restart. */
+		Restart = 'restart',
+
+		/** The runtime exited because of an error, most often a crash. */
+		Error = 'error',
+
+		/**
+		 * The runtime exited for an unknown reason. This typically means that
+		 * it exited unexpectedly but with a normal exit code (0).
+		 */
+		Unknown = 'unknown',
+	}
+
+	/**
+	 * LanguageRuntimeExit is an interface that defines an event occurring when a
+	 * language runtime exits.
+	 */
+	export interface LanguageRuntimeExit {
+		/**
+		 * The process exit code, if the runtime is backed by a process. If the
+		 * runtime is not backed by a process, this should just be 0 for a
+		 * succcessful exit and 1 for an error.
+		 */
+		exit_code: number;
+
+		/**
+		 * The reason the runtime exited.
+		 */
+		reason: RuntimeExitReason;
+
+		/** The exit message, if any. */
+		message: string;
+	}
+
 	/**
 	 * LanguageRuntimeMessage is an interface that defines an event occurring in a
 	 * language runtime, such as outputting text or plots.
@@ -444,6 +491,9 @@ declare module 'positron' {
 		/** An object that emits the current state of the runtime */
 		onDidChangeRuntimeState: vscode.Event<RuntimeState>;
 
+		/** An object that emits an event when the user's session ends and the runtime exits */
+		onDidEndSession: vscode.Event<LanguageRuntimeExit>;
+
 		/** Execute code in the runtime */
 		execute(code: string,
 			id: string,

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

@@ -37,6 +37,9 @@ export class PythonRuntime implements positron.LanguageRuntime, vscode.Disposabl
     /** The emitter for language runtime state changes */
     private _stateEmitter = new vscode.EventEmitter<positron.RuntimeState>();
 
+    /** The emitter for language runtime exits */
+    private _exitEmitter = new vscode.EventEmitter<positron.LanguageRuntimeExit>();
+
     /** The Jupyter Adapter extension API */
     private adapterApi?: JupyterAdapterApi;
 
@@ -53,6 +56,7 @@ export class PythonRuntime implements positron.LanguageRuntime, vscode.Disposabl
         this._queue = new PQueue({ concurrency: 1 });
         this.onDidReceiveRuntimeMessage = this._messageEmitter.event;
         this.onDidChangeRuntimeState = this._stateEmitter.event;
+        this.onDidEndSession = this._exitEmitter.event;
 
         this.onDidChangeRuntimeState((state) => {
             this.onStateChange(state);
@@ -63,6 +67,8 @@ export class PythonRuntime implements positron.LanguageRuntime, vscode.Disposabl
 
     onDidChangeRuntimeState: vscode.Event<positron.RuntimeState>;
 
+    onDidEndSession: vscode.Event<positron.LanguageRuntimeExit>;
+
     execute(
         code: string,
         id: string,
@@ -244,6 +250,9 @@ export class PythonRuntime implements positron.LanguageRuntime, vscode.Disposabl
         kernel.onDidReceiveRuntimeMessage((message) => {
             this._messageEmitter.fire(message);
         });
+        kernel.onDidEndSession((exit) => {
+            this._exitEmitter.fire(exit);
+        });
         return kernel;
     }