VS Code Extension API

Relevant source files

• extensions/vscode-api-tests/package.json
• extensions/vscode-api-tests/src/singlefolder-tests/chat.test.ts
• extensions/vscode-api-tests/src/singlefolder-tests/languages.test.ts
• extensions/vscode-api-tests/src/singlefolder-tests/terminal.test.ts
• extensions/vscode-api-tests/src/singlefolder-tests/window.test.ts
• extensions/vscode-api-tests/src/singlefolder-tests/workspace.event.test.ts
• extensions/vscode-api-tests/src/singlefolder-tests/workspace.tasks.test.ts
• extensions/vscode-colorize-tests/src/colorizer.test.ts
• src/vs/editor/common/config/editorConfigurationSchema.ts
• src/vs/editor/common/config/editorOptions.ts
• src/vs/editor/common/languages.ts
• src/vs/editor/common/services/languageFeatures.ts
• src/vs/editor/common/services/languageFeaturesService.ts
• src/vs/editor/common/standalone/standaloneEnums.ts
• src/vs/editor/contrib/gotoSymbol/browser/goToCommands.ts
• src/vs/editor/contrib/gotoSymbol/browser/goToSymbol.ts
• src/vs/editor/contrib/gotoSymbol/browser/link/clickLinkGesture.ts
• src/vs/editor/contrib/gotoSymbol/browser/link/goToDefinitionAtPosition.css
• src/vs/editor/contrib/gotoSymbol/browser/link/goToDefinitionAtPosition.ts
• src/vs/editor/contrib/inPlaceReplace/browser/inPlaceReplace.css
• src/vs/editor/contrib/inPlaceReplace/browser/inPlaceReplace.ts
• src/vs/editor/contrib/inlayHints/browser/inlayHintsLocations.ts
• src/vs/editor/contrib/inlineCompletions/browser/controller/commandIds.ts
• src/vs/editor/contrib/inlineCompletions/browser/controller/commands.ts
• src/vs/editor/contrib/inlineCompletions/browser/controller/inlineCompletionContextKeys.ts
• src/vs/editor/contrib/inlineCompletions/browser/controller/inlineCompletionsController.ts
• src/vs/editor/contrib/inlineCompletions/browser/inlineCompletions.contribution.ts
• src/vs/editor/contrib/inlineCompletions/browser/model/inlineCompletionsModel.ts
• src/vs/editor/contrib/inlineCompletions/browser/model/inlineCompletionsSource.ts
• src/vs/editor/contrib/inlineCompletions/browser/model/inlineSuggestionItem.ts
• src/vs/editor/contrib/inlineCompletions/browser/model/provideInlineCompletions.ts
• src/vs/editor/contrib/inlineCompletions/browser/telemetry.ts
• src/vs/editor/contrib/inlineCompletions/browser/view/inlineEdits/inlineEditWithChanges.ts
• src/vs/editor/contrib/inlineCompletions/browser/view/inlineEdits/inlineEditsModel.ts
• src/vs/editor/contrib/inlineCompletions/browser/view/inlineEdits/inlineEditsView.ts
• src/vs/editor/contrib/inlineCompletions/browser/view/inlineEdits/inlineEditsViewInterface.ts
• src/vs/editor/contrib/inlineCompletions/browser/view/inlineEdits/inlineEditsViewProducer.ts
• src/vs/editor/contrib/links/browser/links.css
• src/vs/editor/contrib/links/browser/links.ts
• src/vs/editor/standalone/browser/standaloneLanguages.ts
• src/vs/monaco.d.ts
• src/vs/platform/extensions/common/extensionsApiProposals.ts
• src/vs/workbench/api/browser/mainThreadChatAgents2.ts
• src/vs/workbench/api/browser/mainThreadEditorTabs.ts
• src/vs/workbench/api/browser/mainThreadLanguageFeatures.ts
• src/vs/workbench/api/browser/mainThreadNotebook.ts
• src/vs/workbench/api/common/extHost.api.impl.ts
• src/vs/workbench/api/common/extHost.protocol.ts
• src/vs/workbench/api/common/extHostChatAgents2.ts
• src/vs/workbench/api/common/extHostDiagnostics.ts
• src/vs/workbench/api/common/extHostEditorTabs.ts
• src/vs/workbench/api/common/extHostLanguageFeatures.ts
• src/vs/workbench/api/common/extHostNotebook.ts
• src/vs/workbench/api/common/extHostTypeConverters.ts
• src/vs/workbench/api/common/extHostTypes.ts
• src/vs/workbench/api/test/browser/extHostDiagnostics.test.ts
• src/vs/workbench/api/test/browser/extHostEditorTabs.test.ts
• src/vs/workbench/api/test/browser/extHostLanguageFeatures.test.ts
• src/vs/workbench/contrib/notebook/browser/media/notebook.css
• src/vs/workbench/contrib/notebook/browser/notebook.contribution.ts
• src/vs/workbench/contrib/notebook/browser/notebookBrowser.ts
• src/vs/workbench/contrib/notebook/browser/notebookEditor.ts
• src/vs/workbench/contrib/notebook/browser/notebookEditorWidget.ts
• src/vs/workbench/contrib/notebook/browser/notebookExtensionPoint.ts
• src/vs/workbench/contrib/notebook/browser/view/notebookCellList.ts
• src/vs/workbench/contrib/notebook/browser/view/renderers/backLayerWebView.ts
• src/vs/workbench/contrib/notebook/browser/view/renderers/cellRenderer.ts
• src/vs/workbench/contrib/notebook/browser/view/renderers/webviewMessages.ts
• src/vs/workbench/contrib/notebook/browser/view/renderers/webviewPreloads.ts
• src/vs/workbench/contrib/notebook/browser/viewModel/baseCellViewModel.ts
• src/vs/workbench/contrib/notebook/browser/viewModel/codeCellViewModel.ts
• src/vs/workbench/contrib/notebook/browser/viewModel/markupCellViewModel.ts
• src/vs/workbench/contrib/notebook/common/model/notebookCellTextModel.ts
• src/vs/workbench/contrib/notebook/common/model/notebookTextModel.ts
• src/vs/workbench/contrib/notebook/common/notebookCommon.ts
• src/vs/workbench/contrib/notebook/common/notebookEditorModel.ts
• src/vs/workbench/contrib/notebook/common/notebookOutputRenderer.ts
• src/vs/workbench/contrib/notebook/common/notebookService.ts
• src/vscode-dts/vscode.d.ts
• src/vscode-dts/vscode.proposed.chatParticipantAdditions.d.ts
• src/vscode-dts/vscode.proposed.inlineCompletionsAdditions.d.ts

The VS Code Extension API is the primary interface through which extensions interact with the workbench. It is implemented as a decoupled system where the extension code runs in a dedicated Extension Host process, while the editor UI and core logic reside in the Main Thread (Renderer process). Communication between these two occurs over an RPC protocol using Data Transfer Objects (DTOs).

API Factory and Initialization

The vscode API object available to extensions is not a simple static object but is dynamically constructed by the API factory. This factory pattern ensures that each extension host (whether local, remote, or web-worker) receives an implementation tailored to its environment while maintaining a consistent surface area defined in vscode.d.ts [src/vscode-dts/vscode.d.ts:6-7].

Key Initialization Steps

1. Actor Registration: The factory registers "actors" or "proxies" for various subsystems (e.g., ExtHostDocuments, ExtHostLanguageFeatures, ExtHostChatAgents2). [src/vs/workbench/api/common/extHost.api.impl.ts:34-105]
2. Service Injection: It utilizes the IExtHostRpcService to establish the connection back to the Main Thread via MainContext and ExtHostContext identifiers. [src/vs/workbench/api/common/extHost.api.impl.ts:94-94]
3. Namespace Construction: It builds the vscode namespace by aggregating services into categories like workspace, window, languages, and chat. [src/vs/workbench/api/common/extHost.api.impl.ts:1030-1050]

API Construction Flow

The following diagram illustrates how the vscode object is instantiated and how it maps internal implementation classes to the public API.

Sources: [src/vs/workbench/api/common/extHost.api.impl.ts:34-105], [src/vs/workbench/api/common/extHost.protocol.ts:33-33]

Data Transfer Objects (DTOs) and Serialization

Because the Extension Host and the Main Thread are in separate processes, they cannot share live objects. Every piece of data sent across the boundary must be serialized into a DTO.

The DTO Pattern

• extHostTypes: These are the classes extensions use directly (e.g., vscode.Range, vscode.Position). They often contain helper methods like contains(). [src/vs/workbench/api/common/extHostTypes.ts:27-45]
• extHostTypeConverters: These utility functions transform extHostTypes into plain JSON-compatible objects (DTOs). For example, typeConvert.Range.from converts a vscode.Range to an extHostProtocol.IRange. [src/vs/workbench/api/common/extHostTypeConverters.ts:30-30]
• UriDto: A specialized DTO for URIs, ensuring that vscode.Uri objects are correctly revived as URI instances on the other side. [src/vs/workbench/api/common/extHost.protocol.ts:18-18]

Serialization Example: Notebooks

When a notebook kernel provides output, the flow is:

1. Extension: Returns a vscode.NotebookCellOutput (from extHostTypes). [src/vs/workbench/api/common/extHostTypes.ts:42-42]
2. ExtHost: typeConvert.NotebookCellOutput.from converts it to an extHostProtocol.INotebookOutputDto. [src/vs/workbench/api/common/extHostTypeConverters.ts:58-60]
3. RPC: The DTO is sent to the Main Thread.
4. Main Thread: MainThreadNotebooks receives the DTO and passes it to the NotebookTextModel in the renderer.

Sources: [src/vs/workbench/api/common/extHost.protocol.ts:1-50], [src/vs/workbench/api/common/extHostTypeConverters.ts:1-40], [src/vs/workbench/api/common/extHostTypes.ts:1-50]

Main Thread Actors

Main Thread actors (prefixed with MainThread) are the "customers" of the Extension Host. They reside in the workbench and implement the Shape interfaces defined in the RPC protocol [src/vs/workbench/api/common/extHost.protocol.ts:33-36].

Key Actors and Responsibilities

Main Thread Class	Responsibility	ExtHost Peer
MainThreadLanguageFeatures	Registers providers in ILanguageFeaturesService	ExtHostLanguageFeatures
MainThreadDocuments	Syncs text model changes to the ext host	ExtHostDocuments
MainThreadChatAgents2	Manages chat participants and progress streams	ExtHostChatAgents2
MainThreadNotebooks	Orchestrates notebook model and kernel communication	ExtHostNotebookController

Interaction Sequence: Language Features

Sources: [src/vs/workbench/api/browser/mainThreadLanguageFeatures.ts:46-62], [src/vs/workbench/api/common/extHostLanguageFeatures.ts:44-105], [src/vs/workbench/api/common/extHost.protocol.ts:33-36]

Chat Agent Streams

Chat Agents use a streaming pattern to provide real-time feedback. ExtHostChatAgents2 manages the response stream via ChatAgentResponseStream, pushing progress chunks to the main thread. [src/vs/workbench/api/common/extHostChatAgents2.ts:44-60]

Progress Handling

The ChatAgentResponseStream handles various types of progress, such as markdown content, references, and tool calls.

• DTO Conversion: Parts like warnings, references, or thinking parts are converted using extHostTypeConverters. [src/vs/workbench/api/common/extHostTypeConverters.ts:46-56]
• Tool Invocation: External tool invocations are streamed to the main thread via $handleProgressChunk with serialized tool data. [src/vs/workbench/api/common/extHost.protocol.ts:68-68]

DTO Mapping Table

Extension API Type (vscode.d.ts)	DTO Interface (extHost.protocol.ts)	Internal Editor/Workbench Type
Position	IPosition	IPosition (editor)
ChatResponsePart	IChatResponsePart	IChatResponsePart
CompletionItem	ISuggestDataDto	CompletionItem (editor)
Location	ILocationDto	Location (editor)

Sources: [src/vs/workbench/api/common/extHostTypes.ts:43-50], [src/vs/workbench/api/common/extHost.protocol.ts:36-36], [src/vs/editor/common/languages.ts:18-20], [src/vs/workbench/api/common/extHostTypeConverters.ts:46-56]