API: Edit session identifier provider

[joyceerhl]

Problem

There is currently support for Continue Working On with Edit Sessions from web to Codespaces, desktop to vscode.dev, desktop to Codespaces. This works by propagating an edit session identifier (a guid) through query parameters and passing it into the workbench creation options.

We would now also like to have Edit Sessions support for Continue Working On from web to desktop, desktop to desktop, etc. This would allow us to have full feature parity with the existing Continue Working On experience, as well as the ability to bring uncommitted changes with you. The following existing scenarios are to be supported:

• github.dev -> clone locally
• RemoteHub desktop -> clone locally
• RemoteHub desktop -> clone in a container volume (Remote Containers)

To do this we have a few options:

1. Propagate the edit session identifier in all entrypoints to desktop, i.e.
   • Protocol handler for extensions (web -> desktop)
   • vscode.openFolder command args (desktop -> desktop)
   • This has the advantage of being extremely unambiguous about which edit session should be associated with the current workspace
2. Enable VS Code to figure out the relevant edit session identifier
   • Ultimately an edit session is an opaque JSON object consisting of some data to be applied to a particular VS Code state
   • We want enough metadata associated with this data so that we don't apply the wrong state
   • The relevant state here is repository identity
   • As initial customers, this API should be implemented by Remote Repositories and the builtin git extension
   • This API would also eventually be needed to enable the scenario where you never lose your RemoteHub changes, i.e. edit sessions are saved without explicitly invoking the store command or the Continue Working On command, and they are automatically resumed without explicitly invoking resume. That will be a complicated scenario to get right so we don't want to go after it yet
   • This proposal lets us have increased confidence that the latest edit session is relevant to the current workspace, without requiring us to introduce the edit session identifier into more places in VS Code (eventually potentially allowing us to remove our reliance on the query parameter approach in the web embedder case). It also potentially improves the reliability of the edit session resume mechanism, because we are not at the mercy of transient faults like the embedder dropping query parameters resulting in the edit session association being lost, for example

Proposal

Reference implementation: #157733

Here are some examples of the actual structure of data that we'd put into the returned workspace identifier:

1. For https://github.dev/microsoft/vscode, https://vscode.dev/github/microsoft/vscode, as well as clones of https://github.com/microsoft/vscode:

   {
       "remote": "https://github.com/microsoft/vscode",
       "ref": "main",
       "sha": "0eac052eb7f7bcd42c587f91b300fd07b89a3ba2"
   }

2. For https://vscode.dev/azurerepos/monacotools/Monaco/Monaco?path=%2F&version=GBmaster and clones of https://dev.azure.com/monacotools/_git/Monaco?path=%2F&version=GBmaster:

   {
       "remote": "https://dev.azure.com/monacotools/_git/Monaco?path=%2F&version=GBmaster",
       "ref": "master",
       "sha": "10c286cfdf73ea7429df686fa5a382d87777f99c"
   }

[joyceerhl]

@TylerLeonhardt also proposed that we could use this API to disambiguate repositories cloned across different machines, so that a user would only have to trust a given repository once across all their clones of the same repo.

[joyceerhl]

@jrieken @bpasero and I chatted about this API proposal today since we ran out of time during the usual API call. The major feedback was:

• In future if this API is used for workspace trust or roaming workspaces, it should probably be renamed from EditSessionIdentity to WorkspaceSessionIdentifier or similar
• The current implementation assumes that there can only be one valid provider for a workspace with file scheme, however it should eventually be possible that a given workspace may have multiple providers e.g. if it is backed up to multiple remote hosting services. In this case:
  • the API implementation needs to either tolerate multiple providers registering for the same scheme, or otherwise introduce more expressive registration so that I can have identity providers from the builtin git extension and OneDrive extension for example
  • the edit sessions implementation and UI should support displaying edit sessions associated with multiple sources
• If a user wants to continue working on a workspace that currently lacks an identifier, there should be an onboarding path for them to use edit sessions, which would likely create additional API needs
• In future when we support auto-backup of edit sessions, we should see if edit sessions can benefit from the work that local history has done to make periodic backups performant
• There may be UX implications of the autoStore setting since communicating with a cloud service before window unload is likely to be long-running
• We could support multiple edit sessions available for a given identifier (e.g. originating from multiple machines) without needing to modify this API (e.g. by storing a manifest of all edit session GUIDs associated with a given identifier)

Please feel free to edit if I missed anything!