# Kernel Status Cleanup

## Existing Implementations

### Jupyter Client

The messaging [spec](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-status) defines the following execution states:

`('busy', 'idle', 'starting')`

### Jupyter Server

Jupyter Server is providing the following states as [`execution_state`](https://github.com/jupyter-server/jupyter_server/blob/606487adbbade8483bc804e4b7010dbfce77c131/jupyter_server/services/api/api.yaml#L756):

`('busy', 'idle', 'starting', 'dead')`

It starts out as "starting" and is dangled on an `execution_state` attribute of the kernel manager. Then it is updated by watching [iopub](https://github.com/jupyter-server/jupyter_server/blob/7239666c231c733cb49ed2f5c18369051c255e9a/jupyter_server/services/kernels/kernelmanager.py#L520). It adds a `dead` state when a kernel manager has a `ready` promise that [errors](https://github.com/jupyter-server/jupyter_server/blob/25ec3ed0dad617a4388db865e9c1a585e54c0b7c/jupyter_server/services/kernels/handlers.py#L386). In that case it also adds a `reason` attribute to the model that the front end can use to display an error.

### JupyterLab

JupyterLab defines the following [statuses](https://github.com/jupyterlab/jupyterlab/blob/62e0591922e3ec8393af7a1e17c8d5438ece22f9/packages/services/src/kernel/messages.ts#L534):

  | 'unknown'
  | 'starting'
  | 'idle'
  | 'busy'
  | 'terminating'
  | 'restarting'
  | 'autorestarting'
  | 'dead';

It updates the status based on [`iopub messages`](https://github.com/jupyterlab/jupyterlab/blob/c82fb0015b60c81b4d3319eb2a3b187ce35a2536/packages/services/src/kernel/default.ts#L1456), or manually in the case of [`autorestarting`](https://github.com/jupyterlab/jupyterlab/blob/c82fb0015b60c81b4d3319eb2a3b187ce35a2536/packages/services/src/kernel/default.ts#L1447) and `restarting`. It uses `unknown` at startup or when we are not connected. The `dead` status is both handled internally and when there
is a `dead` execution state given when fetch
the kernel model after a failed websocket [connection](https://github.com/jupyterlab/jupyterlab/blob/c82fb0015b60c81b4d3319eb2a3b187ce35a2536/packages/services/src/kernel/default.ts#L1284).

The `terminating` state was added in [jupyterlab#8562](https://github.com/jupyterlab/jupyterlab/pull/8562) but it is only used by the [`SessionContext`](https://github.com/jupyterlab/jupyterlab/blob/62e0591922e3ec8393af7a1e17c8d5438ece22f9/packages/apputils/src/sessioncontext.tsx#L771) in a `statusChanged` signal, but it does not expose a `status` property.

JupyterLab also has a [ConnectionStatus](https://github.com/jupyterlab/jupyterlab/blob/2f648bca377ad6074344f3eae21e3cee90a25363/packages/services/src/kernel/kernel.ts#L904) that reflects the state of the WebSocket connection.

## Proposal

Jupyter Client should preserve the existing `execution_state` semantics, and do its own tracking, offering an `execution_state` property.
It should add a `status` field reflecting the
status of the subprocess. It should remove the
`ready` promise, but preserve the `use_pending_kernels` option. It should also
have an API for waiting for a state to move into
a desired state. It should also offer a "reason"
property for when it enters a dead state.

Jupyter Server should continue to provide the
underlying `execution_state` in its kernel model,
but also provide the `status` property if it is
available. When using pending kernels and connecting to a websocket, it should use the
new Jupyter Client API to wait for the state to
be finalized.

JupyterLab should use the new "status" and
"reason" model fields instead of doing its own
internal handling of kernel status. It should separate the concept of execution_state from kernel status. In the case
where a WebSocket connect errors, it should update its status from the status field if given
and the reason field if given. It should deprecate any statuses that would not have
been provided by Jupyter Client and add handling
for new ones as appropriate.