@posit-dev/positron/dist/positron.d.ts

TypeScript definitions and runtime utilities for the Positron API

/*---------------------------------------------------------------------------------------------
 *  Copyright (C) 2023-2025 Posit Software, PBC. All rights reserved.
 *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
 *--------------------------------------------------------------------------------------------*/

/// <reference path="../vscode-dts/vscode.proposed.chatProvider.d.ts" />
/// <reference path="../vscode-dts/vscode.proposed.languageModelThinkingPart.d.ts" />

declare module 'positron' {

	import * as vscode from 'vscode';

	/**
	 * The current Positron version. This is the Positron calendar version, e.g. "2028.10.2"
	 */
	export const version: string;

	/**
	 * The Positron build number. This is a monotonically increasing number that uniquely
	 * identifies a build of Positron within a release.
	 */
	export const buildNumber: number;

	/** The set of possible language runtime messages */
	export enum LanguageRuntimeMessageType {
		/** A message instructing the frontend to clear the output of a runtime execution. */
		ClearOutput = 'clear_output',

		/** A message representing output (text, plots, etc.) */
		Output = 'output',

		/** A message representing the computational result of a runtime execution */
		Result = 'result',

		/** A message representing output from one of the standard streams (stdout or stderr) */
		Stream = 'stream',

		/** A message representing echoed user input */
		Input = 'input',

		/** A message representing an error that occurred while executing user code */
		Error = 'error',

		/** A message representing a prompt for user input */
		Prompt = 'prompt',

		/** A message representing a change in the runtime's online state */
		State = 'state',

		/** A message representing a runtime event */
		Event = 'event',

		/** A message representing a new comm (client instance) being opened from the runtime side */
		CommOpen = 'comm_open',

		/** A message representing data received via a comm (to a client instance) */
		CommData = 'comm_data',

		/** A message indicating that a comm (client instance) was closed from the server side */
		CommClosed = 'comm_closed',

		/** A message representing a debug event to the frontend */
		DebugEvent = 'debug_event',

		/** A message representing a debug reply to the frontend */
		DebugReply = 'debug_reply',

		/** A message that should be handled by an IPyWidget */
		IPyWidget = 'ipywidget',

		/** A message representing a request to update an output */
		UpdateOutput = 'update_output',
	}

	/**
	 * The set of possible statuses for a language runtime while online
	 */
	export enum RuntimeOnlineState {
		/** The runtime is starting up */
		Starting = 'starting',

		/** The runtime is ready to execute code. */
		Idle = 'idle',

		/** The runtime is busy executing code. */
		Busy = 'busy',
	}

	/**
	 * The set of possible statuses for a language runtime
	 */
	export enum RuntimeState {
		/** The runtime has not been started or initialized yet. */
		Uninitialized = 'uninitialized',

		/** The runtime is initializing (preparing to start). */
		Initializing = 'initializing',

		/** The runtime is in the process of starting up. It isn't ready for messages. */
		Starting = 'starting',

		/** The runtime has a heartbeat and is ready for messages. */
		Ready = 'ready',

		/** The runtime is ready to execute code. */
		Idle = 'idle',

		/** The runtime is busy executing code. */
		Busy = 'busy',

		/** The runtime is in the process of restarting. */
		Restarting = 'restarting',

		/** The runtime is in the process of shutting down. */
		Exiting = 'exiting',

		/** The runtime's host process has ended. */
		Exited = 'exited',

		/** The runtime is not responding to heartbeats and is presumed offline. */
		Offline = 'offline',

		/** The user has interrupted a busy runtime, but the runtime is not idle yet. */
		Interrupting = 'interrupting',
	}

	/**
	 * Results of analyzing code fragment for completeness
	 */
	export enum RuntimeCodeFragmentStatus {
		/** The code fragment is complete: it is a valid, self-contained expression */
		Complete = 'complete',

		/** The code is incomplete: it is an expression that is missing elements or operands, such as "1 +" or "foo(" */
		Incomplete = 'incomplete',

		/** The code is invalid: an expression that cannot be parsed because of a syntax error */
		Invalid = 'invalid',

		/** It was not possible to ascertain the code fragment's status */
		Unknown = 'unknown'
	}

	/**
	 * Possible code execution modes for a language runtime
	 */
	export enum RuntimeCodeExecutionMode {
		/**
		 * Interactive code execution:
		 *          Displayed to user: Yes
		 * Combined with pending code: Yes
		 *          Stored in history: Yes
		 */
		Interactive = 'interactive',

		/**
		 * Non-interactive code execution:
		 *          Displayed to user: Yes
		 * Combined with pending code: No
		 *          Stored in history: Yes
		 */
		NonInteractive = 'non-interactive',

		/**
		 * Transient code execution:
		 *          Displayed to user: Yes
		 * Combined with pending code: No
		 *          Stored in history: No
		 */
		Transient = 'transient',

		/**
		 * Silent code execution:
		 *          Displayed to user: No
		 * Combined with pending code: No
		 *          Stored in history: No
		 */
		Silent = 'silent'
	}

	/**
	 * Possible error dispositions for a language runtime
	 */
	export enum RuntimeErrorBehavior {
		/** The runtime should stop when an error is encountered. */
		Stop = 'stop',

		/** The runtime should continue execution when an error is encountered */
		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 is exiting in order to switch to a new runtime. */
		SwitchRuntime = 'switchRuntime',

		/** The runtime exited because of an error, most often a crash. */
		Error = 'error',

		/**
		 * The runtime session was transferred somewhere else. This happens when
		 * it is loaded into a different Positron window; it 'exits' from the
		 * old window and is reconnected in the new window.
		 */
		Transferred = 'transferred',

		/** The runtime exited because the extension hosting it was stopped. */
		ExtensionHost = 'extensionHost',

		/**
		 * 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 {
		/** Runtime name */
		runtime_name: string;

		/** Session name */
		session_name: string;

		/**
		 * 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.
	 */
	export interface LanguageRuntimeMessage {
		/** The event ID */
		id: string;

		/** The ID of this event's parent (the event that caused it), if applicable */
		parent_id: string;

		/** The message's date and time, in ISO 8601 format */
		when: string;

		/** The type of event */
		type: LanguageRuntimeMessageType;

		/** Additional metadata, if any */
		metadata?: Record<string, unknown>;

		/** Additional binary data, if any */
		buffers?: Array<Uint8Array>;
	}

	/**
	 * LanguageRuntimeClearOutput is a LanguageRuntimeMessage instructing the frontend to clear the
	 * output of a runtime execution. */
	export interface LanguageRuntimeClearOutput extends LanguageRuntimeMessage {
		/** Wait to clear the output until new output is available. */
		wait: boolean;
	}

	/** LanguageRuntimeOutput is a LanguageRuntimeMessage representing output (text, plots, etc.) */
	export interface LanguageRuntimeOutput extends LanguageRuntimeMessage {
		/** A record of data MIME types to the associated data, e.g. `text/plain` => `'hello world'` */
		data: Record<string, unknown>;

		/**
		 * The optional identifier of the output. If specified, this output can be referenced
		 * in future messages e.g. when {@link LanguageRuntimeUpdateOutput updating an output}.
		 */
		output_id?: string;
	}

	/**
	 * LanguageRuntimeUpdateOutput is a LanguageRuntimeMessage instructing the frontend
	 * to update an existing output.
	 */
	export interface LanguageRuntimeUpdateOutput extends LanguageRuntimeMessage {
		/** The updated output data */
		data: Record<string, unknown>;

		/** The identifier of the output to update */
		output_id: string;
	}

	/**
	 * LanguageRuntimeResult is a LanguageRuntimeOutput representing the computational result of a
	 * runtime execution.
	 */
	export interface LanguageRuntimeResult extends LanguageRuntimeOutput {
	}

	/**
	 * The set of possible output locations for a LanguageRuntimeOutput.
	 */
	export enum PositronOutputLocation {
		/** The output should be displayed inline in Positron's Console */
		Console = 'console',

		/** The output should be displayed in Positron's Viewer pane */
		Viewer = 'viewer',

		/** The output should be displayed in Positron's Plots pane */
		Plot = 'plot',
	}

	/**
	 * LanguageRuntimeWebOutput amends LanguageRuntimeOutput with additional information needed
	 * to render web content in Positron.
	 */
	export interface LanguageRuntimeWebOutput extends LanguageRuntimeOutput {
		/** Where the web output should be displayed */
		output_location: PositronOutputLocation;

		/** The set of resource roots needed to display the output */
		resource_roots: vscode.Uri[];
	}

	/**
	 * The set of standard stream names supported for streaming textual output.
	 */
	export enum LanguageRuntimeStreamName {
		Stdout = 'stdout',
		Stderr = 'stderr'
	}

	/**
	 * LanguageRuntimeStream is a LanguageRuntimeMessage representing output from a standard stream
	 * (stdout or stderr).
	 */
	export interface LanguageRuntimeStream extends LanguageRuntimeMessage {
		/** The stream name */
		name: LanguageRuntimeStreamName;

		/** The stream's text */
		text: string;
	}

	/** LanguageRuntimeInput is a LanguageRuntimeMessage representing echoed user input */
	export interface LanguageRuntimeInput extends LanguageRuntimeMessage {
		/** The code that was input */
		code: string;

		/** The execution count */
		execution_count: number;
	}

	/** LanguageRuntimePrompt is a LanguageRuntimeMessage representing a prompt for input */
	export interface LanguageRuntimePrompt extends LanguageRuntimeMessage {
		/** The prompt text */
		prompt: string;

		/** Whether this is a password prompt (and typing should be hidden)  */
		password: boolean;
	}

	/** LanguageRuntimeInfo contains metadata about the runtime after it has started. */
	export interface LanguageRuntimeInfo {
		/** A startup banner */
		banner: string;

		/** The implementation version number */
		implementation_version: string;

		/** The language version number */
		language_version: string;

		/** List of supported features (e.g., 'debugger' for Jupyter debugging protocol support) */
		supported_features?: string[];

		/** Initial prompt string in case user customized it */
		input_prompt?: string;

		/** Continuation prompt string in case user customized it */
		continuation_prompt?: string;
	}

	/** LanguageRuntimeState is a LanguageRuntimeMessage representing a new runtime state */
	export interface LanguageRuntimeState extends LanguageRuntimeMessage {
		/** The new state */
		state: RuntimeOnlineState;
	}

	/** LanguageRuntimeError is a LanguageRuntimeMessage that represents a run-time error */
	export interface LanguageRuntimeError extends LanguageRuntimeMessage {
		/** The error name */
		name: string;

		/** The error message */
		message: string;

		/** The error stack trace */
		traceback: Array<string>;
	}

	/**
	 * LanguageRuntimeMessageIPyWidget is a wrapped LanguageRuntimeMessage that should be handled
	 * by an IPyWidget.
	 *
	 * Output widgets may intercept replies to an execution and instead render them inside the
	 * output widget. See https://ipywidgets.readthedocs.io/en/latest/examples/Output%20Widget.html
	 * for more.
	 */
	export interface LanguageRuntimeMessageIPyWidget extends LanguageRuntimeMessage {
		/** The original runtime message that was intercepted by an IPyWidget */
		original_message: LanguageRuntimeMessage;
	}

	/**
	 * LanguageRuntimeCommOpen is a LanguageRuntimeMessage that indicates a
	 * comm (client instance) was opened from the server side
	 */
	export interface LanguageRuntimeCommOpen extends LanguageRuntimeMessage {
		/** The unique ID of the comm being opened */
		comm_id: string;

		/** The name (type) of the comm being opened, e.g. 'jupyter.widget' */
		target_name: string;

		/** The data from the back-end */
		data: object;
	}

	/** LanguageRuntimeCommMessage is a LanguageRuntimeMessage that represents data for a comm (client instance) */
	export interface LanguageRuntimeCommMessage extends LanguageRuntimeMessage {
		/** The unique ID of the client comm ID for which the message is intended */
		comm_id: string;

		/** The data from the back-end */
		data: object;
	}

	/**
	 * LanguageRuntimeCommClosed is a LanguageRuntimeMessage that indicates a
	 * comm (client instance) was closed from the server side
	 */
	export interface LanguageRuntimeCommClosed extends LanguageRuntimeMessage {
		/** The unique ID of the client comm ID for which the message is intended */
		comm_id: string;

		/** The data from the back-end */
		data: object;
	}

	/** A DebugProtocolRequest is an opaque stand-in type for the [Request](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Request) type defined in the Debug Adapter Protocol. */
	export interface DebugProtocolRequest {
		// Properties: see [Request details](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Request).
	}

	/** A DebugProtocolResponse is an opaque stand-in type for the [Response](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Response) type defined in the Debug Adapter Protocol. */
	export interface DebugProtocolResponse {
		// Properties: see [Response details](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Response).
	}

	/**
	 * A DebugProtocolEvent is an opaque stand-in type for the [Event](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Event) type defined in the Debug Adapter Protocol.
	 */
	export interface DebugProtocolEvent {
		// Properties: see [Event details](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Event).
	}

	/**
	 * LanguageRuntimeDebugReply is a LanguageRuntimeMessage that represents a reply to a runtime debugger.
	 */
	export interface LanguageRuntimeDebugReply extends LanguageRuntimeMessage {
		/** The debug adapter protocol response.  */
		content: DebugProtocolResponse;
	}

	/**
	 * LanguageRuntimeDebugEvent is a LanguageRuntimeMessage that represents an event from the runtime debugger.
	 */
	export interface LanguageRuntimeDebugEvent extends LanguageRuntimeMessage {
		/** The debug adapter protocol event. */
		content: DebugProtocolEvent;
	}

	/**
	 * LanguageRuntimeMetadata contains information about a language runtime that is known
	 * before the runtime is started.
	 */
	export interface LanguageRuntimeMetadata {
		/** The path to the runtime. */
		runtimePath: string;

		/** A unique identifier for this runtime; takes the form of a GUID */
		runtimeId: string;

		/**
		 * The fully qualified name of the runtime displayed to the user; e.g. "R 4.2 (64-bit)".
		 * Should be unique across languages.
		 */
		runtimeName: string;

		/**
		 * A language specific runtime name displayed to the user; e.g. "4.2 (64-bit)".
		 * Should be unique within a single language.
		 */
		runtimeShortName: string;

		/** The version of the runtime itself (e.g. kernel or extension version) as a string; e.g. "0.1" */
		runtimeVersion: string;

		/** The runtime's source or origin; e.g. PyEnv, System, Homebrew, Conda, etc. */
		runtimeSource: string;

		/** The free-form, user-friendly name of the language this runtime can execute; e.g. "R" */
		languageName: string;

		/**
		 * The Visual Studio Code Language ID of the language this runtime can execute; e.g. "r"
		 *
		 * See here for a list of known language IDs:
		 * https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers
		 */
		languageId: string;

		/** The version of the language; e.g. "4.2" */
		languageVersion: string;

		/** The Base64-encoded icon SVG for the language. */
		base64EncodedIconSvg: string | undefined;

		/** Whether the runtime should start up automatically or wait until explicitly requested */
		startupBehavior: LanguageRuntimeStartupBehavior;

		/** Where sessions will be located; used as a hint to control session restoration */
		sessionLocation: LanguageRuntimeSessionLocation;

		/**
		 * Extra data supplied by the runtime provider; not read by Positron but supplied
		 * when creating a new session from the metadata.
		 */
		extraRuntimeData: any;

		/**
		 * Subscriptions to notifications from the UI. When subscribed, the frontend sends
		 * notifications to the backend via the UI client.
		 */
		uiSubscriptions?: UiRuntimeNotifications[];
	}

	/**
	 * UI notifications from frontend to backends.
	 */
	export enum UiRuntimeNotifications {
		/** Notification that the settings for rendering a plot have changed, typically because the plot area did */
		DidChangePlotsRenderSettings = 'did_change_plots_render_settings',
	}

	export interface RuntimeSessionMetadata {
		/** The ID of this session */
		readonly sessionId: string;

		/** The session's mode */
		readonly sessionMode: LanguageRuntimeSessionMode;

		/** The URI of the notebook document associated with the session, if any */
		readonly notebookUri?: vscode.Uri;

		/** The starting working directory of the session, if any */
		readonly workingDirectory?: string;
	}

	/**
	 * LanguageRuntimeSessionMode is an enum representing the set of possible
	 * modes for a language runtime session.
	 */
	export enum LanguageRuntimeSessionMode {
		/**
		 * The runtime session is bound to a Positron console. Typically,
		 * there's only one console session per language.
		 */
		Console = 'console',

		/** The runtime session backs a notebook. */
		Notebook = 'notebook',

		/** The runtime session is a background session (not attached to any UI). */
		Background = 'background',
	}


	/**
	 * LanguageRuntimeDynState contains information about a language runtime that may
	 * change after a runtime has started.
	 */
	export interface LanguageRuntimeDynState {
		/** The text the language's interpreter uses to prompt the user for input, e.g. ">" or ">>>" */
		inputPrompt: string;

		/** The text the language's interpreter uses to prompt the user for continued input, e.g. "+" or "..." */
		continuationPrompt: string;

		/** The user-facing name of this session */
		sessionName: string;
	}

	export enum LanguageRuntimeStartupBehavior {
		/**
		 * The runtime should be started immediately after registration; usually used for runtimes
		 * that are affiliated with the current workspace.
		 */
		Immediate = 'immediate',

		/**
		 * The runtime should start automatically; usually used for runtimes that provide LSPs
		 */
		Implicit = 'implicit',

		/**
		 * The runtime should start when the user explicitly requests it;
		 * usually used for runtimes that only provide REPLs
		 */
		Explicit = 'explicit',

		/**
		 * The runtime only starts up if manually requested by the user.
		 * The difference from Explicit, is that Manual startup never
		 * starts automatically, even if the run time is affiliated to the
		 * workspace.
		 */
		Manual = 'manual'
	}

	/**
	 * An enumeration of possible locations for runtime sessions.
	 */
	export enum LanguageRuntimeSessionLocation {
		/**
		 * The runtime session is persistent on the machine; it should be
		 * restored when the workspace is re-opened, and may persist across
		 * Positron sessions.
		 */
		Machine = 'machine',

		/**
		 * The runtime session is located in the current workspace (usually a
		 * terminal); it should be restored when the workspace is re-opened in
		 * the same Positron session (e.g. during a browser reload or
		 * reconnect)
		 */
		Workspace = 'workspace',

		/**
		 * The runtime session is browser-only; it should not be restored when the
		 * workspace is re-opened.
		 */
		Browser = 'browser',
	}

	/**
	 * The set of client types that can be generated by a language runtime. Note
	 * that, because client types can share a namespace with other kinds of
	 * widgets, each client type in Positron's API is prefixed with the string
	 * "positron".
	 */
	export enum RuntimeClientType {
		Variables = 'positron.variables',
		Lsp = 'positron.lsp',
		Plot = 'positron.plot',
		DataExplorer = 'positron.dataExplorer',
		Ui = 'positron.ui',
		Help = 'positron.help',
		Connection = 'positron.connection',
		Reticulate = 'positron.reticulate',
		IPyWidget = 'jupyter.widget',
		IPyWidgetControl = 'jupyter.widget.control',

		// Future client types may include:
		// - Watch window/variable explorer
		// - Code inspector
		// - etc.
	}

	/**
	 * The possible states for a language runtime client instance. These
	 * represent the state of the communications channel between the client and
	 * the runtime.
	 */
	export enum RuntimeClientState {
		/** The client has not yet been initialized */
		Uninitialized = 'uninitialized',

		/** The connection between the server and the client is being opened */
		Opening = 'opening',

		/** The connection between the server and the client has been established */
		Connected = 'connected',

		/** The connection between the server and the client is being closed */
		Closing = 'closing',

		/** The connection between the server and the client is closed */
		Closed = 'closed',
	}

	/**
	 * A variable in the runtime's memory or environment.
	 */
	export interface RuntimeVariable {
		/** An internal access key for the variable */
		access_key: string;

		/** A human-readable display name for the variable */
		display_name: string;

		/** The type of the variable (string, number, etc.) */
		display_type: string;

		/** A string representation of the value of the variable */
		display_value: string;

		/**
		 * Extended type information naming e.g. the exact class name of the
		 * variable
		 */
		type_info?: string;

		/** The length of the variable, e.g. number of elements in an array */
		length: number;

		/** The size of a variable, e.g. in bytes */
		size: number;

		/** Whether the variable has child variables, e.g columns in a data frame */
		has_children: boolean;
	}

	/**
	 * A result of calling the QuerySessionTables API.
	 */
	export interface QueryTableSummaryResult {
		/**
		 * The total number of rows in the table.
		 */
		num_rows: number;

		/**
		 * The total number of columns in the table.
		 */
		num_columns: number;

		/**
		 * The column schemas in the table.
		 */
		column_schemas: Array<string>;

		/**
		 * The column profiles in the table.
		 */
		column_profiles: Array<string>;

	}

	/**
	 * The possible types of language model that can be used with the Positron Assistant.
	 */
	export enum PositronLanguageModelType {
		Chat = 'chat',
		Completion = 'completion',
	}

	/**
	 * The possible locations a Positron Assistant chat request can be invoked from.
	 */
	export enum PositronChatAgentLocation {
		Panel = 'panel',
		Terminal = 'terminal',
		Notebook = 'notebook',
		Editor = 'editor',
	}

	/**
	 * The possible modes for a Positron Assistant chat request.
	 */
	export enum PositronChatMode {
		Ask = 'ask',
		Edit = 'edit',
		Agent = 'agent',
	}

	/**
	 * A message received from a runtime client instance.
	 */
	export interface RuntimeClientOutput<T> {
		/** The message data */
		data: T;

		/** Raw binary data associated with the message, if any */
		buffers?: Array<Uint8Array>;
	}

	/**
	 * An instance of a client widget generated by a language runtime. See
	 * RuntimeClientType for the set of possible client types.
	 *
	 * The client is responsible for disposing itself when it is no longer
	 * needed; this will trigger the closure of the communications channel
	 * between the client and the runtime.
	 */
	export interface RuntimeClientInstance extends vscode.Disposable {
		onDidChangeClientState: vscode.Event<RuntimeClientState>;
		onDidSendEvent: vscode.Event<RuntimeClientOutput<object>>;
		performRpcWithBuffers<T>(data: object): Thenable<RuntimeClientOutput<T>>;
		performRpc<T>(data: object): Thenable<T>;
		getClientState(): RuntimeClientState;
		getClientId(): string;
		getClientType(): RuntimeClientType;
	}

	/**
	 * Code attribution sources for code executed by Positron.
	 */
	export enum CodeAttributionSource {
		/** The code was executed by an AI assistant. */
		Assistant = 'assistant',

		/** The code was executed by a Positron extension. */
		Extension = 'extension',

		/** The code was executed interactively (the user typed it in). */
		Interactive = 'interactive',

		/** The code was executed from a notebook cell. */
		Notebook = 'notebook',

		/** The code was pasted into the Console. */
		Paste = 'paste',

		/** The code was run as a fragment or whole of a script. */
		Script = 'script',
	}

	/**
	 * Code attribution metadata for code executed by Positron.
	 */
	export interface CodeAttribution {
		/** The code's origin */
		source: CodeAttributionSource;

		/**
		 * Additional metadata specific to the attribution source, if any. For
		 * example, when code is executed from an extension, it names the
		 * extension, and when code is executed from a script, it names the
		 * script.
		 */
		metadata?: Record<string, any>;
	}

	/**
	 * An event that is emitted when code is executed in Positron.
	 */
	export interface CodeExecutionEvent {
		/** The ID of the code execution. */
		executionId: string;

		/** The ID of the language in which the code was executed (e.g. 'python') */
		languageId: string;

		/** The name of the runtime that executed the code (e.g. 'Python 3.12') */
		runtimeName: string;

		/** The actual code that was executed. */
		code: string;

		/** An object describing the origin of the code. */
		attribution: CodeAttribution;
	}

	export interface LanguageRuntimeManager {
		/**
		 * Returns a generator that yields metadata about all the language
		 * runtimes that are available to the user.
		 *
		 * This metadata will be passed to `createSession` to create new runtime
		 * sessions.
		 */
		discoverAllRuntimes(): AsyncGenerator<LanguageRuntimeMetadata>;

		/**
		 * Returns a single runtime metadata object representing the runtime
		 * that should be used in the current workspace, if any.
		 *
		 * Note that this is called before `discoverAllRuntimes` during
		 * startup, and should return `undefined` if no runtime is recommended.
		 *
		 * If a runtime is returned, `startupBehavior` property of the runtime
		 * metadata is respected here; use `Immediately` to start the runtime
		 * right away, or any other value to save the runtime as the project
		 * default without starting it.
		 */
		recommendedWorkspaceRuntime(): Thenable<LanguageRuntimeMetadata | undefined>;

		/**
		 * An optional event that fires when a new runtime is discovered.
		 *
		 * Not fired during `discoverRuntimes()`; used to notify Positron of a
		 * new runtime or environment after the initial discovery has completed.
		 */
		onDidDiscoverRuntime?: vscode.Event<LanguageRuntimeMetadata>;

		/**
		 * An optional metadata validation function. If provided, Positron will
		 * validate any stored metadata before attempting to use it to create a
		 * new session. This happens when a workspace is re-opened, for example.
		 *
		 * If the metadata is invalid, the function should return a new version
		 * of the metadata with the necessary corrections.
		 *
		 * If it is not possible to correct the metadata, the function should
		 * reject with an error.
		 *
		 * @param metadata The metadata to validate
		 * @returns A Thenable that resolves with an updated version of the
		 *   metadata.
		 */
		validateMetadata?(metadata: LanguageRuntimeMetadata):
			Thenable<LanguageRuntimeMetadata>;

		/**
		 * An optional session validation function. If provided, Positron will
		 * validate any stored session metadata before reconnecting to the
		 * session.
		 *
		 * @param metadata The metadata to validate
		 * @returns A Thenable that resolves with true (the session is valid) or
		 *  false (the session is invalid).
		 */
		validateSession?(sessionId: string): Thenable<boolean>;

		/**
		 * Creates a new runtime session.
		 *
		 * @param runtimeMetadata One of the runtime metadata items returned by
		 * `discoverRuntimes`.
		 * @param sessionMetadata The metadata for the new session.
		 *
		 * @returns A Thenable that resolves with the new session, or rejects with an error.
		 */
		createSession(runtimeMetadata: LanguageRuntimeMetadata,
			sessionMetadata: RuntimeSessionMetadata):
			Thenable<LanguageRuntimeSession>;

		/**
		 * Reconnects to a runtime session using the given metadata.
		 *
		 * Implementing this method is optional, since not all sessions can be
		 * reconnected; for example, sessions that run in the browser cannot be
		 * reconnected.
		 *
		 * @param runtimeMetadata The metadata for the runtime that owns the
		 * session.
		 * @param sessionMetadata The metadata for the session to reconnect.
		 * @param sessionName The name of the session to reconnect.
		 * @returns A Thenable that resolves with the reconnected session, or
		 * rejects with an error.
		 */
		restoreSession?(runtimeMetadata: LanguageRuntimeMetadata,
			sessionMetadata: RuntimeSessionMetadata,
			sessionName: string):
			Thenable<LanguageRuntimeSession>;
	}

	/**
	 * An enum representing the set of runtime method error codes; these map to
	 * JSON-RPC error codes.
	 */
	export enum RuntimeMethodErrorCode {
		ParseError = -32700,
		InvalidRequest = -32600,
		MethodNotFound = -32601,
		InvalidParams = -32602,
		InternalError = -32603,
		ServerErrorStart = -32000,
		ServerErrorEnd = -32099
	}

	/**
	 * An error returned by a runtime method call.
	 */
	export interface RuntimeMethodError {
		/** An error code */
		code: RuntimeMethodErrorCode;

		/** A human-readable error message */
		message: string;

		/**
		 * A name for the error, for compatibility with the Error object.
		 * Usually `RPC Error ${code}`.
		 */
		name: string;

		/** Additional error information (optional) */
		data: any | undefined;
	}

	/**
	 * Enum of available channels for a language runtime session.
	 * Used to enumerate available channels for users.
	 */
	export enum LanguageRuntimeSessionChannel {
		Console = 'console',
		Kernel = 'kernel',
		LSP = 'lsp',
	}

	/**
	 * Basic metadata about an active language runtime session, including
	 * immutable metadata about the session itself and metadata about the
	 * runtime with which it is associated.
	 */
	export interface ActiveRuntimeSessionMetadata {
		/** An object supplying immutable metadata about this specific session */
		readonly metadata: RuntimeSessionMetadata;

		/**
		 * An object supplying metadata about the runtime with which this
		 * session is associated.
		 */
		readonly runtimeMetadata: LanguageRuntimeMetadata;
	}

	/**
	 * Base interface for a language runtime session.
	 *
	 * This is the version of a language runtime session that is returned by
	 * Positron's API methods; it provides basic access to the session for use
	 * by extensions other that the one that created the session.
	 */
	export interface BaseLanguageRuntimeSession extends ActiveRuntimeSessionMetadata {

		/** The state of the runtime that changes during a user session */
		getDynState(): Thenable<LanguageRuntimeDynState>;

		/**
		 * Calls a method in the runtime and returns the result.
		 *
		 * Throws a RuntimeMethodError if the method call fails.
		 *
		 * @param method The name of the method to call
		 * @param args Arguments to pass to the method
		 */
		callMethod?(method: string, ...args: any[]): Thenable<any>;

		/**
		 * Execute code in the runtime
		 *
		 * @param code The code to execute
		 * @param id The ID of the code
		 * @param mode The code execution mode
		 * @param errorBehavior The code execution error behavior
		 * Note: The errorBehavior parameter is currently ignored by kernels
		 */
		execute(code: string,
			id: string,
			mode: RuntimeCodeExecutionMode,
			errorBehavior: RuntimeErrorBehavior): void;

		/**
		 * Shut down the runtime; returns a Thenable that resolves when the
		 * runtime shutdown sequence has been successfully started (not
		 * necessarily when it has completed).
		 */
		shutdown(exitReason: RuntimeExitReason): Thenable<void>;
	}

	/**
	 * LanguageRuntimeSession is the full interface implemented by extensions
	 * that provide a set of common tools for interacting with a language
	 * runtime, such as code execution, LSP implementation, and plotting.
	 */
	export interface LanguageRuntimeSession extends BaseLanguageRuntimeSession, vscode.Disposable {

		/** Information about the runtime that is only available after starting. */
		readonly runtimeInfo: LanguageRuntimeInfo | undefined;

		/** An object that emits language runtime events */
		onDidReceiveRuntimeMessage: vscode.Event<LanguageRuntimeMessage>;

		/** 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>;

		/**
		 * Opens a resource in the runtime.
		 * @param resource The resource to open.
		 * @returns true if the resource was opened; otherwise, false.
		 */
		openResource?(resource: vscode.Uri | string): Thenable<boolean>;

		/**
		 * Sends a Debug Adapter Protocol request to the runtime's debugger.
		 *
		 * @param request The Debug Adapter Protocol request.
		 * @returns The Debug Adapter Protocol response.
		 */
		debug(request: DebugProtocolRequest): Thenable<DebugProtocolResponse>;

		/** Test a code fragment for completeness */
		isCodeFragmentComplete(code: string): Thenable<RuntimeCodeFragmentStatus>;

		/**
		 * Create a new instance of a client; return null if the client type
		 * is not supported by this runtime, or a string containing the ID of
		 * the client if it is supported.
		 *
		 * @param id The unique, client-supplied ID of the client instance. Can be any
		 *   unique string.
		 * @param type The type of client to create
		 * @param params A set of parameters to pass to the client; specific to the client type
		 * @param metadata A set of metadata to pass to the client; specific to the client type
		 */
		createClient(id: string, type: RuntimeClientType, params: Record<string, unknown>, metadata?: Record<string, unknown>): Thenable<void>;

		/**
		 * List all clients, optionally filtered by type.
		 *
		 * @param type If specified, only clients of this type will be returned.
		 * @returns A Thenable that resolves with a map of client IDs to client types.
		 */
		listClients(type?: RuntimeClientType): Thenable<Record<string, string>>;

		/** Remove an instance of a client (created with `createClient`) */
		removeClient(id: string): void;

		/**
		 * Send a message to the server end of a client instance. Any replies to the message
		 * will be sent back to the client via the `onDidReceiveRuntimeMessage` event, with
		 * the `parent_id` field set to the `message_id` given here.
		 */
		sendClientMessage(client_id: string, message_id: string, message: Record<string, unknown>): void;

		/** Reply to a prompt issued by the runtime */
		replyToPrompt(id: string, reply: string): void;

		/**
		 * Set the current working directory of the session.
		 */
		setWorkingDirectory(dir: string): Thenable<void>;

		/**
		 * Start the session; returns a Thenable that resolves with information about the runtime.
		 * If the runtime fails to start for any reason, the Thenable should reject with an error
		 * object containing a `message` field with a human-readable error message and an optional
		 * `details` field with additional information.
		 */
		start(): Thenable<LanguageRuntimeInfo>;

		/**
		 * Interrupt the runtime; returns a Thenable that resolves when the interrupt has been
		 * successfully sent to the runtime (not necessarily when it has been processed)
		 */
		interrupt(): Thenable<void>;

		/**
		 * Restart the runtime; returns a Thenable that resolves when the runtime restart sequence
		 * has been successfully started (not necessarily when it has completed). A restart will
		 * cause the runtime to be shut down and then started again; its status will change from
		 * `Restarting` => `Exited` => `Initializing` => `Starting` => `Ready`.
		 *
		 * @param workingDirectory The new working directory to use for the
		 * restarted runtime, if any. Use `undefined` to keep the current
		 * working directory.
		 */
		restart(workingDirectory?: string): Thenable<void>;

		/**
		 * Forcibly quits the runtime; returns a Thenable that resolves when the
		 * runtime has been terminated. This may be called by Positron if the
		 * runtime fails to respond to an interrupt and/or shutdown call, and
		 * should forcibly terminate any underlying processes.
		 */
		forceQuit(): Thenable<void>;

		/**
		 * Update the session name.
		 *
		 * @param sessionName The new session name
		 */
		updateSessionName(sessionName: string): void;

		/**
		 * Show runtime log in output panel.
		 *
		 * @param channel The channel to show the output in
		 */
		showOutput?(channel?: LanguageRuntimeSessionChannel): void;

		/**
		 * Return a list of output channels
		 *
		 * @returns A list of output channels available on this runtime
		 */
		listOutputChannels?(): LanguageRuntimeSessionChannel[];

		/**
		 * Show profiler log if supported.
		 */
		showProfile?(): Thenable<void>;
	}


	/**
	 * A data structure that describes a handler for a runtime client instance,
	 * and is called when an instance is created.
	 *
	 * @param client The client instance that was created
	 * @param params A set of parameters passed to the client
	 * @returns true if the handler took ownership of the client, false otherwise
	 */
	export type RuntimeClientHandlerCallback = (
		client: RuntimeClientInstance,
		params: Object,) => boolean;

	/**
	 * A data structure that describes a handler for a runtime client instance.
	 */
	export interface RuntimeClientHandler {
		/**
		 * The type of client that this handler handles.
		 */
		clientType: string;

		/**
		 * A callback that is called when a client of the given type is created;
		 * returns whether the handler took ownership of the client.
		 */
		callback: RuntimeClientHandlerCallback;
	}

	/**
	 * Content settings for webviews hosted in the Preview panel.
	 *
	 * This interface mirrors the `WebviewOptions` & `WebviewPanelOptions` interfaces, with
	 * the following exceptions:
	 *
	 * - `enableFindWidget` is not supported (we never show it in previews)
	 * - `retainContextWhenHidden` is not supported (we always retain context)
	 * - `enableCommandUris` is not supported (we never allow commands in previews)
	 */
	export interface PreviewOptions {
		/**
		 * Controls whether scripts are enabled in the webview content or not.
		 *
		 * Defaults to false (scripts-disabled).
		 */
		readonly enableScripts?: boolean;

		/**
		 * Controls whether forms are enabled in the webview content or not.
		 *
		 * Defaults to true if {@link PreviewOptions.enableScripts scripts are enabled}. Otherwise defaults to false.
		 * Explicitly setting this property to either true or false overrides the default.
		 */
		readonly enableForms?: boolean;

		/**
		 * Root paths from which the webview can load local (filesystem) resources using uris from `asWebviewUri`
		 *
		 * Default to the root folders of the current workspace plus the extension's install directory.
		 *
		 * Pass in an empty array to disallow access to any local resources.
		 */
		readonly localResourceRoots?: readonly vscode.Uri[];

		/**
		 * Mappings of localhost ports used inside the webview.
		 *
		 * Port mapping allow webviews to transparently define how localhost ports are resolved. This can be used
		 * to allow using a static localhost port inside the webview that is resolved to random port that a service is
		 * running on.
		 *
		 * If a webview accesses localhost content, we recommend that you specify port mappings even if
		 * the `webviewPort` and `extensionHostPort` ports are the same.
		 *
		 * *Note* that port mappings only work for `http` or `https` urls. Websocket urls (e.g. `ws://localhost:3000`)
		 * cannot be mapped to another port.
		 */
		readonly portMapping?: readonly vscode.WebviewPortMapping[];
	}

	/**
	 * A preview panel that contains a webview. This interface mirrors the
	 * `WebviewPanel` interface, but omits elements that don't apply to
	 * preview panels, such as `viewColumn`.
	 */
	export interface PreviewPanel {
		/**
		 * Identifies the type of the preview panel, such as `'markdown.preview'`.
		 */
		readonly viewType: string;

		/**
		 * Title of the panel shown in UI.
		 */
		title: string;

		/**
		 * {@linkcode Webview} belonging to the panel.
		 */
		readonly webview: vscode.Webview;

		/**
		 * Whether the panel is active (focused by the user).
		 */
		readonly active: boolean;

		/**
		 * Whether the panel is visible.
		 */
		readonly visible: boolean;

		/**
		 * Fired when the panel's view state changes.
		 */
		readonly onDidChangeViewState: vscode.Event<PreviewPanelOnDidChangeViewStateEvent>;

		/**
		 * Fired when the panel is disposed.
		 *
		 * This may be because the user closed the panel or because `.dispose()` was
		 * called on it.
		 *
		 * Trying to use the panel after it has been disposed throws an exception.
		 */
		readonly onDidDispose: vscode.Event<void>;

		/**
		 * Show the preview panel
		 *
		 * Only one preview panel can be shown at a time. If a different preview
		 * is already showing, it will be hidden.
		 *
		 * @param preserveFocus When `true`, the webview will not take focus.
		 */
		reveal(preserveFocus?: boolean): void;

		/**
		 * Dispose of the preview panel.
		 *
		 * This closes the panel if it showing and disposes of the resources
		 * owned by the underlying webview.  Preview panels are also disposed
		 * when the user closes the preview panel. Both cases fire the
		 * `onDispose` event.
		 */
		dispose(): any;
	}

	/**
	 * Event fired when a preview panel's view state changes.
	 */
	export interface PreviewPanelOnDidChangeViewStateEvent {
		/**
		 * Preview panel whose view state changed.
		 */
		readonly previewPanel: PreviewPanel;
	}

	/**
	 * The type of source that opened a preview.
	 */
	export enum PreviewSourceType {
		/** The preview was opened by a language runtime. */
		Runtime = 'runtime',
		/** The preview was opened by a terminal. */
		Terminal = 'terminal',
	}

	/**
	 * Source information for preview content, indicating what opened the preview.
	 */
	export interface PreviewSource {
		/**
		 * The type of source that opened the preview.
		 */
		readonly type: PreviewSourceType;

		/**
		 * The ID of the source. For 'runtime', this is the session ID;
		 * for 'terminal', this is the terminal process ID.
		 */
		readonly id: string;
	}

	export interface StatementRangeProvider {
		/**
		 * Given a cursor position, return the range of the statement that the
		 * cursor is within. If the cursor is not within a statement, return the
		 * range of the next statement, if one exists.
		 *
		 * @param document The document in which the command was invoked.
		 * @param position The position at which the command was invoked.
		 * @param token A cancellation token.
		 * @return The range of the statement at the given position.
		 */
		provideStatementRange(document: vscode.TextDocument,
			position: vscode.Position,
			token: vscode.CancellationToken): vscode.ProviderResult<StatementRange>;
	}

	/**
	 * The range of a statement, plus optionally the code for the range.
	 */
	export interface StatementRange {
		/**
		 * The range of the statement at the given position.
		 */
		readonly range: vscode.Range;

		/**
		 * The code for this statement range, if different from the document contents at this range.
		 */
		readonly code?: string;

	}

	export interface HelpTopicProvider {
		/**
		 * Given a cursor position, return the help topic relevant to the cursor
		 * position, or an empty string if no help topic is recommended or
		 * relevant.
		 *
		 * @param document The document in which the command was invoked.
		 * @param position The position at which the command was invoked.
		 * @param token A cancellation token.
		 * @return A string containing the help topic relevant to the cursor
		 *   position
		 */
		provideHelpTopic(document: vscode.TextDocument,
			position: vscode.Position,
			token: vscode.CancellationToken): vscode.ProviderResult<string>;
	}

	export interface Console {
		/**
		 * Pastes text into the console.
		 */
		pasteText(text: string): void;
	}

	/**
	 * ConnectionsInput interface defines the structure for connection inputs.
	 */
	export interface ConnectionsInput {
		/**
		 * The unique identifier for the input.
		 */
		id: string;
		/**
		 * A human-readable label for the input.
		 */
		label: string;
		/**
		 * The type of the input.
		 */
		// eslint-disable-next-line local/vscode-dts-literal-or-types, local/vscode-dts-string-type-literals
		type: 'string' | 'number' | 'option';
		/**
		 * Options, if the input type is an option.
		 */
		options?: { 'identifier': string; 'title': string }[];
		/**
		 * The default value for the input.
		 */
		value?: string;
	}

	/**
	 * ConnectionsDriverMetadata interface defines the structure for connection driver metadata.
	 */
	export interface ConnectionsDriverMetadata {
		/**
		 * The language identifier for the driver.
		 * Drivers are grouped by language, not by runtime.
		 */
		languageId: string;
		/**
		 * A human-readable name for the driver.
		 */
		name: string;
		/**
		 * The base64-encoded SVG icon for the driver.
		 */
		base64EncodedIconSvg?: string;
		/**
		 * The inputs required to create a connection.
		 * For instance, a connection might require a username
		 * and password.
		 */
		inputs: Array<ConnectionsInput>;
	}

	export interface ConnectionsDriver {
		/**
		 * The unique identifier for the driver.
		 */
		driverId: string;

		/**
		 * The metadata for the driver.
		 */
		metadata: ConnectionsDriverMetadata;

		/**
		 * Generates the connection code based on the inputs.
		 */
		generateCode?: (inputs: Array<ConnectionsInput>) => string;

		/**
		 * Connect session.
		 */
		connect?: (code: string) => Thenable<void>;

		/**
		 * Checks if the dependencies for the driver are installed
		 * and functioning.
		 */
		checkDependencies?: () => Thenable<boolean>;

		/**
		 * Installs the dependencies for the driver.
		 * For instance, R packages would install the required
		 * R packages, and or other dependencies.
		 */
		installDependencies?: () => Thenable<boolean>;
	}

	/**
	 * Settings necessary to render a plot in the format expected by the plot widget.
	 */
	export interface PlotRenderSettings {
		size: {
			width: number;
			height: number;
		};
		pixel_ratio: number;
		format: PlotRenderFormat;
	}

	/**
	 * Possible formats for rendering a plot.
	 */
	export enum PlotRenderFormat {
		Png = 'png',
		Jpeg = 'jpeg',
		Svg = 'svg',
		Pdf = 'pdf',
		Tiff = 'tiff'
	}

	namespace languages {
		/**
		 * Register a statement range provider.
		 *
		 * @param selector A selector that defines the documents this provider is applicable to.
		 * @param provider A statement range provider.
		 * @return A {@link Disposable} that unregisters this provider when being disposed.
		 */
		export function registerStatementRangeProvider(
			selector: vscode.DocumentSelector,
			provider: StatementRangeProvider): vscode.Disposable;

		/**
		 * Register a help topic provider.
		 *
		 * @param selector A selector that defines the documents this provider is applicable to.
		 * @param provider A help topic provider.
		 * @return A {@link Disposable} that unregisters this provider when being disposed.
		 */
		export function registerHelpTopicProvider(
			selector: vscode.DocumentSelector,
			provider: HelpTopicProvider): vscode.Disposable;
	}

	namespace window {
		/**
		 * Create and show a new preview panel.
		 *
		 * @param viewType Identifies the type of the preview panel.
		 * @param title Title of the panel.
		 * @param options Settings for the new panel.
		 *
		 * @return New preview panel.
		 */
		export function createPreviewPanel(viewType: string, title: string, preserveFocus?: boolean, options?: PreviewOptions): PreviewPanel;

		/**
		 * Create and show a new preview panel for a URL. This is a convenience
		 * method that creates a new webview panel and sets its content to the
		 * given URL.
		 *
		 * @param url The URL to preview
		 * @param source Optional source information indicating what opened the preview
		 *
		 * @return New preview panel.
		 */
		export function previewUrl(url: vscode.Uri, source?: PreviewSource): PreviewPanel;

		/**
		 * Create and show a new preview panel for an HTML fil