Proposal: Streamline code execution via the extension API

[seeM]

The current positron.runtime.executeCode function resolves when the code is sent to the runtime. However, in both the Positron R and Positron Notebook Controller extensions we construct a promise that resolves when the code is handled by the runtime (by waiting for the status idle message), or rejects after a timeout.

The latter seems much more useful for language packs and other extensions so possibly worth streamlining.

Proposal:

Update positron.runtime.executeCode to:

1. Resolve when the session receives a status idle message.
2. Reject after a configurable timeout.
3. Accept a callback: (message) => void that is called on each received runtime message with the same parent ID as the execution ID.

[jmcphers]

This functionality was frequently requested by the team developing the R extension, though we never got around to implementing it. I bet other extension authors would also find it very beneficial.

I think it would also be important for the promise to reject if the code causes an error to occur, as an important use case (for R) was running some code on the user's behalf and knowing both (a) whether it finished, and (b) whether it ran successfully. There are also other rejection cases, such as the runtime exited/being shut down/restarted/interrupted during execution.

We could probably leave it up to the caller to wrap the promise in a timeout if needed.

[seeM]

There's an initial attempt at this in the positron-notebook-controllers extension.

[juliasilge]

Extension developers would also benefit from this type of functionality, as outlined in https://github.com/posit-dev/positron/discussions/6729

[jmcphers]

This is now done. The executeCode API has been updated with two important changes:

https://github.com/posit-dev/positron/blob/a13271d188e96f7122aa296a66fa4f17f73be966/src/positron-dts/positron.d.ts#L1476-L1498

• It now returns a promise that resolves when the code is done running, not when it sent to the console. The promise resolves with the result of the evaluation (in the form of a dictionary of MIME types)
• A new parameter allows you to attach an ExecutionObserver when running code. This observer will be notified in real time (not at the end) as output is emitted from the execution, and can also be used to cancel the execution.

[jonvanausdeln]

I don't see a way to test this directly, but all the run in console features seem to still be working, as does the new assistant feature. All e2e tests are passing.