@theia/plugin 1.55.1 → 1.57.0-next.22

package/README.md

@@ -192,6 +192,7 @@ Simple example that show a status bar message with statusBarItem:
         item.text = 'test status bar item';
         item.show();
 ```
+
 #### Output channel API
 
  It is possible to show a container for readonly textual information:
@@ -241,9 +242,10 @@ const terminal = theia.window.createTerminal("Bash terminal", "/bin/bash", ["-l"
 ```
 
 Where are:
- - first argument - terminal's name.
- - second argument - path to the executable shell.
- - third argument - arguments to configure executable shell.
+
+- first argument - terminal's name.
+- second argument - path to the executable shell.
+- third argument - arguments to configure executable shell.
 
 You can create terminal with specific options:
 
@@ -258,10 +260,11 @@ const options: theia.TerminalOptions {
 ```
 
 Where are:
- - "shellPath" - path to the executable shell, for example "/bin/bash", "bash", "sh" or so on.
- - "shellArgs" - shell command arguments, for example without login: "-l". If you defined shell command "/bin/bash" and set up shell arguments "-l" than will be created terminal process with command "/bin/bash -l". And client side will connect to stdin/stdout of this process to interaction with user.
- - "cwd" - current working directory;
- - "env"- environment variables for terminal process, for example TERM - identifier terminal window capabilities.
+
+- "shellPath" - path to the executable shell, for example "/bin/bash", "bash", "sh" or so on.
+- "shellArgs" - shell command arguments, for example without login: "-l". If you defined shell command "/bin/bash" and set up shell arguments "-l" than will be created terminal process with command "/bin/bash -l". And client side will connect to stdin/stdout of this process to interaction with user.
+- "cwd" - current working directory;
+- "env"- environment variables for terminal process, for example TERM - identifier terminal window capabilities.
 
 Function to create new terminal with defined theia.TerminalOptions described above:
 
@@ -288,6 +291,7 @@ terminal.sendText("Hello, Theia!", false);
 ```
 
 Where are:
+
 - first argument - text content.
 - second argument - in case true, terminal will apply new line after the text, otherwise will send only the text.
 
@@ -323,6 +327,7 @@ terminal.processId.then(id => {
 Preference API allows one to read or update User's and Workspace's preferences.
 
 To get preferences:
+
 ```typescript
 // editor preferences
 const preferences = theia.workspace.getConfiguration('editor');
@@ -332,6 +337,7 @@ const fontSize = preferences.get('tabSize');
 ```
 
 To change preference:
+
 ```typescript
 preferences.onDidChangeConfiguration(e => {
     if (e.affectsConfiguration('editor.tabSize')) {
@@ -353,6 +359,7 @@ const diagnostics = theia.languages.getDiagnostics(uriToResource)
 ```
 
 To get all diagnostics use:
+
 ```typescript
 const diagnostics =  theia.languages.getDiagnostics()
 ```
@@ -424,6 +431,7 @@ diagnosticsCollection.forEach((uri, diagnostics) => {
 #### Signature help
 
 To provide signature help form plugin it is required to register provider. For registration 3 items are needed:
+
 - Documents selector to describe for which files it should be applied
 - Handler which will do the work
 - Trigger characters after typing of which the handler should be invoked. Often symbols `(` and `,` are used.
@@ -474,6 +482,7 @@ Example of signature information:
 ```
 
 Note, that:
+
 - `activeSignature` and `activeParameter` are zero based.
 - label is usually full method signature.
 - for documentation fields markdown partially supported (Tags aren't supported).
@@ -762,5 +771,6 @@ function provideRanges(document: theia.TextDocument): theia.ProviderResult<theia
 - [一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception](https://projects.eclipse.org/license/secondary-gpl-2.0-cp)
 
 ## Trademark
+
 "Theia" is a trademark of the Eclipse Foundation
-https://www.eclipse.org/theia
+<https://www.eclipse.org/theia>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.55.1",
+  "version": "1.57.0-next.22+35d458a96",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.55.1"
+    "@theia/ext-scripts": "1.56.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "be4713a778be16ba831af63a6fbd43b2301e882d"
+  "gitHead": "35d458a961212de264d9579305d984147fa55618"
 }

package/src/theia.d.ts

@@ -2163,7 +2163,7 @@ export module '@theia/plugin' {
         /**
          * The icon path or {@link ThemeIcon} for the QuickPickItem.
          */
-        iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+        iconPath?: IconPath;
 
         /**
          * A human-readable string which is rendered less prominent in the same line. Supports rendering of
@@ -2696,6 +2696,11 @@ export module '@theia/plugin' {
      * Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.
      */
     export class ThemeColor {
+        /**
+         * The id of this color.
+         */
+        readonly id: string;
+
         /**
          * Creates a reference to a theme color.
          */
@@ -2735,6 +2740,21 @@ export module '@theia/plugin' {
         private constructor(id: string, color?: ThemeColor);
     }
 
+    /**
+     * Represents an icon in the UI. This is either an uri, separate uris for the light- and dark-themes,
+     * or a {@link ThemeIcon theme icon}.
+     */
+    export type IconPath = Uri | {
+        /**
+         * The icon path for the light theme.
+         */
+        light: Uri;
+        /**
+         * The icon path for the dark theme.
+         */
+        dark: Uri;
+    } | ThemeIcon;
+
     /**
      * Represents the state of a window.
      */
@@ -3515,7 +3535,7 @@ export module '@theia/plugin' {
         /**
          * The icon path or {@link ThemeIcon} for the terminal.
          */
-        iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+        iconPath?: IconPath;
 
         /**
          * The icon {@link ThemeColor} for the terminal.
@@ -3635,7 +3655,7 @@ export module '@theia/plugin' {
         /**
          * The icon path or {@link ThemeIcon} for the terminal.
          */
-        iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+        iconPath?: IconPath;
 
         /**
          * The icon {@link ThemeColor} for the terminal.
@@ -6222,7 +6242,7 @@ export module '@theia/plugin' {
         /**
          * Icon for the button.
          */
-        readonly iconPath: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+        readonly iconPath: IconPath;
 
         /**
          * An optional tooltip.
@@ -6836,7 +6856,7 @@ export module '@theia/plugin' {
          * When `falsy`, {@link ThemeIcon.Folder Folder Theme Icon} is assigned, if item is collapsible otherwise {@link ThemeIcon.File File Theme Icon}.
          * When a {@link ThemeIcon ThemeIcon} is specified, icon is derived from the current file icon theme for the specified theme icon using {@link TreeItem.resourceUri resourceUri} (if provided).
          */
-        iconPath?: string | Uri | { light: string | Uri; dark: string | Uri } | ThemeIcon;
+        iconPath?: string | IconPath;
 
         /**
          * A human readable string which is rendered less prominent.
@@ -10607,7 +10627,7 @@ export module '@theia/plugin' {
         /**
          * The icon path or {@link ThemeIcon ThemeIcon} for the edit.
          */
-        iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+        iconPath?: IconPath;
     }
 
     /**
@@ -17262,6 +17282,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a user request in chat history.
+     * @stubbed
      */
     export class ChatRequestTurn {
         /**
@@ -17289,14 +17310,20 @@ export module '@theia/plugin' {
          */
         readonly references: ChatPromptReference[];
 
+        /**
+         * The list of tools were attached to this request.
+         */
+        readonly toolReferences: readonly ChatLanguageModelToolReference[];
+
         /**
          * @hidden
          */
-        private constructor(prompt: string, command: string | undefined, references: ChatPromptReference[], participant: string);
+        private constructor(prompt: string, command: string | undefined, references: ChatPromptReference[], participant: string, toolReferences: ChatLanguageModelToolReference[]);
     }
 
     /**
      * Represents a chat participant's response in chat history.
+     * @stubbed
      */
     export class ChatResponseTurn {
         /**
@@ -17327,6 +17354,7 @@ export module '@theia/plugin' {
 
     /**
      * Extra context passed to a participant.
+     * @stubbed
      */
     export interface ChatContext {
         /**
@@ -17337,6 +17365,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents an error result from a chat request.
+     * @stubbed
      */
     export interface ChatErrorDetails {
         /**
@@ -17352,6 +17381,7 @@ export module '@theia/plugin' {
 
     /**
      * The result of a chat request.
+     * @stubbed
      */
     export interface ChatResult {
         /**
@@ -17382,6 +17412,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents user feedback for a result.
+     * @stubbed
      */
     export interface ChatResultFeedback {
         /**
@@ -17398,6 +17429,7 @@ export module '@theia/plugin' {
 
     /**
      * A followup question suggested by the participant.
+     * @stubbed
      */
     export interface ChatFollowup {
         /**
@@ -17424,11 +17456,13 @@ export module '@theia/plugin' {
 
     /**
      * Will be invoked once after each request to get suggested followup questions to show the user. The user can click the followup to send it to the chat.
+     * @stubbed
      */
     export interface ChatFollowupProvider {
         /**
          * Provide followups for the given result.
          * @param result This object has the same properties as the result returned from the participant callback, including `metadata`, but is not the same instance.
+         * @param context Extra context passed to a participant.
          * @param token A cancellation token.
          */
         provideFollowups(result: ChatResult, context: ChatContext, token: CancellationToken): ProviderResult<ChatFollowup[]>;
@@ -17436,12 +17470,14 @@ export module '@theia/plugin' {
 
     /**
      * A chat request handler is a callback that will be invoked when a request is made to a chat participant.
+     * @stubbed
      */
     export type ChatRequestHandler = (request: ChatRequest, context: ChatContext, response: ChatResponseStream, token: CancellationToken) => ProviderResult<ChatResult | void>;
 
     /**
      * A chat participant can be invoked by the user in a chat session, using the `@` prefix. When it is invoked, it handles the chat request and is solely
      * responsible for providing a response to the user. A ChatParticipant is created using {@link chat.createChatParticipant}.
+     * @stubbed
      */
     export interface ChatParticipant {
         /**
@@ -17452,16 +17488,7 @@ export module '@theia/plugin' {
         /**
          * An icon for the participant shown in UI.
          */
-        iconPath?: Uri | {
-            /**
-             * The icon path for the light theme.
-             */
-            light: Uri;
-            /**
-             * The icon path for the dark theme.
-             */
-            dark: Uri;
-        } | ThemeIcon;
+        iconPath?: IconPath;
 
         /**
          * The handler for requests to this participant.
@@ -17490,6 +17517,7 @@ export module '@theia/plugin' {
 
     /**
      * A reference to a value that the user added to their chat request.
+     * @stubbed
      */
     export interface ChatPromptReference {
         /**
@@ -17518,6 +17546,7 @@ export module '@theia/plugin' {
 
     /**
      * A request to a chat participant.
+     * @stubbed
      */
     export interface ChatRequest {
         /**
@@ -17545,12 +17574,35 @@ export module '@theia/plugin' {
          * string-manipulation of the prompt.
          */
         readonly references: readonly ChatPromptReference[];
+
+        /**
+         * The list of tools that the user attached to their request.
+         *
+         * When a tool reference is present, the chat participant should make a chat request using
+         * {@link LanguageModelChatToolMode.Required} to force the language model to generate input for the tool. Then, the
+         * participant can use {@link lm.invokeTool} to use the tool attach the result to its request for the user's prompt. The
+         * tool may contribute useful extra context for the user's request.
+         */
+        readonly toolReferences: readonly ChatLanguageModelToolReference[];
+
+        /**
+         * A token that can be passed to {@link lm.invokeTool} when invoking a tool inside the context of handling a chat request.
+         * This associates the tool invocation to a chat session.
+         */
+        readonly toolInvocationToken: ChatParticipantToolToken;
+
+        /**
+         * This is the model that is currently selected in the UI. Extensions can use this or use {@link chat.selectChatModels} to
+         * pick another model. Don't hold onto this past the lifetime of the request.
+         */
+        readonly model: LanguageModelChat;
     }
 
     /**
      * The ChatResponseStream is how a participant is able to return content to the chat view. It provides several methods for streaming different types of content
      * which will be rendered in an appropriate way in the chat view. A participant can use the helper method for the type of content it wants to return, or it
      * can instantiate a {@link ChatResponsePart} and use the generic {@link ChatResponseStream.push} method to return it.
+     * @stubbed
      */
     export interface ChatResponseStream {
         /**
@@ -17567,7 +17619,7 @@ export module '@theia/plugin' {
          * `push(new ChatResponseAnchorPart(value, title))`.
          * An anchor is an inline reference to some type of resource.
          *
-         * @param value A uri, location, or symbol information.
+         * @param value A uri or location.
          * @param title An optional title that is rendered with value.
          */
         anchor(value: Uri | Location, title?: string): void;
@@ -17606,16 +17658,7 @@ export module '@theia/plugin' {
          * @param value A uri or location
          * @param iconPath Icon for the reference shown in UI
          */
-        reference(value: Uri | Location, iconPath?: Uri | ThemeIcon | {
-            /**
-             * The icon path for the light theme.
-             */
-            light: Uri;
-            /**
-             * The icon path for the dark theme.
-             */
-            dark: Uri;
-        }): void;
+        reference(value: Uri | Location, iconPath?: IconPath): void;
 
         /**
          * Pushes a part to this stream.
@@ -17627,6 +17670,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a part of a chat response that is formatted as Markdown.
+     * @stubbed
      */
     export class ChatResponseMarkdownPart {
         /**
@@ -17644,6 +17688,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a file tree structure in a chat response.
+     * @stubbed
      */
     export interface ChatResponseFileTree {
         /**
@@ -17659,6 +17704,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a part of a chat response that is a file tree.
+     * @stubbed
      */
     export class ChatResponseFileTreePart {
         /**
@@ -17681,6 +17727,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a part of a chat response that is an anchor, that is rendered as a link to a target.
+     * @stubbed
      */
     export class ChatResponseAnchorPart {
         /**
@@ -17703,6 +17750,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a part of a chat response that is a progress message.
+     * @stubbed
      */
     export class ChatResponseProgressPart {
         /**
@@ -17719,6 +17767,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a part of a chat response that is a reference, rendered separately from the content.
+     * @stubbed
      */
     export class ChatResponseReferencePart {
         /**
@@ -17729,36 +17778,19 @@ export module '@theia/plugin' {
         /**
          * The icon for the reference.
          */
-        iconPath?: Uri | ThemeIcon | {
-            /**
-             * The icon path for the light theme.
-             */
-            light: Uri;
-            /**
-             * The icon path for the dark theme.
-             */
-            dark: Uri;
-        };
+        iconPath?: IconPath;
 
         /**
          * Create a new ChatResponseReferencePart.
          * @param value A uri or location
          * @param iconPath Icon for the reference shown in UI
          */
-        constructor(value: Uri | Location, iconPath?: Uri | ThemeIcon | {
-            /**
-             * The icon path for the light theme.
-             */
-            light: Uri;
-            /**
-             * The icon path for the dark theme.
-             */
-            dark: Uri;
-        });
+        constructor(value: Uri | Location, iconPath?: IconPath);
     }
 
     /**
      * Represents a part of a chat response that is a button that executes a command.
+     * @stubbed
      */
     export class ChatResponseCommandButtonPart {
         /**
@@ -17813,6 +17845,7 @@ export module '@theia/plugin' {
 
     /**
      * Represents a message in a chat. Can assume different roles, like user or assistant.
+     * @stubbed
      */
     export class LanguageModelChatMessage {
 
@@ -17822,7 +17855,7 @@ export module '@theia/plugin' {
          * @param content The content of the message.
          * @param name The optional name of a user for the message.
          */
-        static User(content: string, name?: string): LanguageModelChatMessage;
+        static User(content: string | (LanguageModelTextPart | LanguageModelToolResultPart)[], name?: string): LanguageModelChatMessage;
 
         /**
          * Utility to create a new assistant message.
@@ -17830,7 +17863,7 @@ export module '@theia/plugin' {
          * @param content The content of the message.
          * @param name The optional name of a user for the message.
          */
-        static Assistant(content: string, name?: string): LanguageModelChatMessage;
+        static Assistant(content: string | (LanguageModelTextPart | LanguageModelToolCallPart)[], name?: string): LanguageModelChatMessage;
 
         /**
          * The role of this message.
@@ -17838,9 +17871,10 @@ export module '@theia/plugin' {
         role: LanguageModelChatMessageRole;
 
         /**
-         * The content of this message.
+         * A string or heterogeneous array of things that a message can contain as content. Some parts may be message-type
+         * specific for some models.
          */
-        content: string;
+        content: (LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart)[];
 
         /**
          * The optional name of a user for this message.
@@ -17854,31 +17888,40 @@ export module '@theia/plugin' {
          * @param content The content of the message.
          * @param name The optional name of a user for the message.
          */
-        constructor(role: LanguageModelChatMessageRole, content: string, name?: string);
+        constructor(role: LanguageModelChatMessageRole, content: string | (LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart)[], name?: string);
     }
 
     /**
      * Represents a language model response.
      *
      * @see {@link LanguageModelAccess.chatRequest}
+     * @stubbed
      */
     export interface LanguageModelChatResponse {
 
         /**
-         * An async iterable that is a stream of text chunks forming the overall response.
+         * An async iterable that is a stream of text and tool-call parts forming the overall response. A
+         * {@link LanguageModelTextPart} is part of the assistant's response to be shown to the user. A
+         * {@link LanguageModelToolCallPart} is a request from the language model to call a tool. The latter will
+         * only be returned if tools were passed in the request via {@link LanguageModelChatRequestOptions.tools}. The
+         * `unknown`-type is used as a placeholder for future parts, like image data parts.
          *
-         * *Note* that this stream will error when during data receiving an error occurs. Consumers of
-         * the stream should handle the errors accordingly.
+         * *Note* that this stream will error when during data receiving an error occurs. Consumers of the stream should handle
+         * the errors accordingly.
          *
-         * To cancel the stream, the consumer can {@link CancellationTokenSource.cancel cancel} the token that was used to make the request
-         * or break from the for-loop.
+         * To cancel the stream, the consumer can {@link CancellationTokenSource.cancel cancel} the token that was used to make
+         * the request or break from the for-loop.
          *
          * @example
          * ```ts
          * try {
          *   // consume stream
-         *   for await (const chunk of response.text) {
-         *    console.log(chunk);
+         *   for await (const chunk of response.stream) {
+         *      if (chunk instanceof LanguageModelTextPart) {
+         *        console.log("TEXT", chunk);
+         *      } else if (chunk instanceof LanguageModelToolCallPart) {
+         *        console.log("TOOL CALL", chunk);
+         *      }
          *   }
          *
          * } catch(e) {
@@ -17887,6 +17930,13 @@ export module '@theia/plugin' {
          * }
          * ```
          */
+        stream: AsyncIterable<LanguageModelTextPart | LanguageModelToolCallPart | unknown>;
+
+        /**
+         * This is equivalent to filtering everything except for text parts from a {@link LanguageModelChatResponse.stream}.
+         *
+         * @see {@link LanguageModelChatResponse.stream}
+         */
         text: AsyncIterable<string>;
     }
 
@@ -17894,6 +17944,7 @@ export module '@theia/plugin' {
      * Represents a language model for making chat requests.
      *
      * @see {@link lm.selectChatModels}
+     * @stubbed
      */
     export interface LanguageModelChat {
 
@@ -17934,8 +17985,8 @@ export module '@theia/plugin' {
          * Make a chat request using a language model.
          *
          * *Note* that language model use may be subject to access restrictions and user consent. Calling this function
-         * for the first time (for a extension) will show a consent dialog to the user and because of that this function
-         * must _only be called in response to a user action!_ Extension can use {@link LanguageModelAccessInformation.canSendRequest}
+         * for the first time (for an extension) will show a consent dialog to the user and because of that this function
+         * must _only be called in response to a user action!_ Extensions can use {@link LanguageModelAccessInformation.canSendRequest}
          * to check if they have the necessary permissions to make a request.
          *
          * This function will return a rejected promise if making a request to the language model is not
@@ -17946,6 +17997,10 @@ export module '@theia/plugin' {
          * - quota limits exceeded, see {@link LanguageModelError.Blocked `Blocked`}
          * - other issues in which case extension must check {@link LanguageModelError.cause `LanguageModelError.cause`}
          *
+         * An extension can make use of language model tool calling by passing a set of tools to
+         * {@link LanguageModelChatRequestOptions.tools}. The language model will return a {@link LanguageModelToolCallPart} and
+         * the extension can invoke the tool and make another request with the result.
+         *
          * @param messages An array of message instances.
          * @param options Options that control the request.
          * @param token A cancellation token which controls the request. See {@link CancellationTokenSource} for how to create one.
@@ -17966,6 +18021,7 @@ export module '@theia/plugin' {
      * Describes how to select language models for chat requests.
      *
      * @see {@link lm.selectChatModels}
+     * @stubbed
      */
     export interface LanguageModelChatSelector {
 
@@ -18001,6 +18057,7 @@ export module '@theia/plugin' {
      * failure causes, like `if(someError.code === vscode.LanguageModelError.NotFound.name) {...}`
      * for the case of referring to an unknown language model. For unspecified errors the `cause`-property
      * will contain the actual error.
+     * @stubbed
      */
     export class LanguageModelError extends Error {
 
@@ -18034,6 +18091,7 @@ export module '@theia/plugin' {
      * Options for making a chat request using a language model.
      *
      * @see {@link LanguageModelChat.sendRequest}
+     * @stubbed
      */
     export interface LanguageModelChatRequestOptions {
 
@@ -18047,6 +18105,24 @@ export module '@theia/plugin' {
          * and need to be lookup in the respective documentation.
          */
         modelOptions?: { [name: string]: any };
+
+        /**
+         * An optional list of tools that are available to the language model. These could be registered tools available via
+         * {@link lm.tools}, or private tools that are just implemented within the calling extension.
+         *
+         * If the LLM requests to call one of these tools, it will return a {@link LanguageModelToolCallPart} in
+         * {@link LanguageModelChatResponse.stream}. It's the caller's responsibility to invoke the tool. If it's a tool
+         * registered in {@link lm.tools}, that means calling {@link lm.invokeTool}.
+         *
+         * Then, the tool result can be provided to the LLM by creating an Assistant-type {@link LanguageModelChatMessage} with a
+         * {@link LanguageModelToolCallPart}, followed by a User-type message with a {@link LanguageModelToolResultPart}.
+         */
+        tools?: LanguageModelChatTool[];
+
+        /**
+         * The tool-selecting mode to use. {@link LanguageModelChatToolMode.Auto} by default.
+         */
+        toolMode?: LanguageModelChatToolMode;
     }
 
     /**
@@ -18087,10 +18163,56 @@ export module '@theia/plugin' {
          * @stubbed
          */
         export function selectChatModels(selector?: LanguageModelChatSelector): Thenable<LanguageModelChat[]>;
+
+        /**
+         * Register a LanguageModelTool. The tool must also be registered in the package.json `languageModelTools` contribution
+         * point. A registered tool is available in the {@link lm.tools} list for any extension to see. But in order for it to
+         * be seen by a language model, it must be passed in the list of available tools in {@link LanguageModelChatRequestOptions.tools}.
+         * @returns A {@link Disposable} that unregisters the tool when disposed.
+         * @stubbed
+         */
+        export function registerTool<T>(name: string, tool: LanguageModelTool<T>): Disposable;
+
+        /**
+         * A list of all available tools that were registered by all extensions using {@link lm.registerTool}. They can be called
+         * with {@link lm.invokeTool} with input that match their declared `inputSchema`.
+         * @stubbed
+         */
+        export const tools: readonly LanguageModelToolInformation[];
+
+        /**
+         * Invoke a tool listed in {@link lm.tools} by name with the given input. The input will be validated against
+         * the schema declared by the tool
+         *
+         * A tool can be invoked by a chat participant, in the context of handling a chat request, or globally by any extension in
+         * any custom flow.
+         *
+         * In the former case, the caller shall pass the
+         * {@link LanguageModelToolInvocationOptions.toolInvocationToken toolInvocationToken}, which comes with the a
+         * {@link ChatRequest.toolInvocationToken chat request}. This makes sure the chat UI shows the tool invocation for the
+         * correct conversation.
+         *
+         * A tool {@link LanguageModelToolResult result} is an array of {@link LanguageModelTextPart text-} and
+         * {@link LanguageModelPromptTsxPart prompt-tsx}-parts. If the tool caller is using `@vscode/prompt-tsx`, it can
+         * incorporate the response parts into its prompt using a `ToolResult`. If not, the parts can be passed along to the
+         * {@link LanguageModelChat} via a user message with a {@link LanguageModelToolResultPart}.
+         *
+         * If a chat participant wants to preserve tool results for requests across multiple turns, it can store tool results in
+         * the {@link ChatResult.metadata} returned from the handler and retrieve them on the next turn from
+         * {@link ChatResponseTurn.result}.
+         *
+         * @param name The name of the tool to call.
+         * @param options The options to use when invoking the tool.
+         * @param token A cancellation token. See {@link CancellationTokenSource} for how to create one.
+         * @returns The result of the tool invocation.
+         * @stubbed
+         */
+        export function invokeTool(name: string, options: LanguageModelToolInvocationOptions<object>, token?: CancellationToken): Thenable<LanguageModelToolResult>;
     }
 
     /**
      * Represents extension specific information about the access to language models.
+     * @stubbed
      */
     export interface LanguageModelAccessInformation {
 
@@ -18109,6 +18231,327 @@ export module '@theia/plugin' {
          * model does not exist or consent hasn't been asked for.
          */
         canSendRequest(chat: LanguageModelChat): boolean | undefined;
+
+    }
+
+    /**
+     * A tool that is available to the language model via {@link LanguageModelChatRequestOptions}. A language model uses all the
+     * properties of this interface to decide which tool to call, and how to call it.
+     * @stubbed
+     */
+    export interface LanguageModelChatTool {
+        /**
+         * The name of the tool.
+         */
+        name: string;
+
+        /**
+         * The description of the tool.
+         */
+        description: string;
+
+        /**
+         * A JSON schema for the input this tool accepts.
+         */
+        inputSchema?: object;
+    }
+
+    /**
+     * A tool-calling mode for the language model to use.
+     */
+    export enum LanguageModelChatToolMode {
+        /**
+         * The language model can choose to call a tool or generate a message. Is the default.
+         */
+        Auto = 1,
+
+        /**
+         * The language model must call one of the provided tools. Note- some models only support a single tool when using this
+         * mode.
+         */
+        Required = 2
+    }
+
+    /**
+     * A language model response part indicating a tool call, returned from a {@link LanguageModelChatResponse}, and also can be
+     * included as a content part on a {@link LanguageModelChatMessage}, to represent a previous tool call in a chat request.
+     * @stubbed
+     */
+    export class LanguageModelToolCallPart {
+        /**
+         * The ID of the tool call. This is a unique identifier for the tool call within the chat request.
+         */
+        callId: string;
+
+        /**
+         * The name of the tool to call.
+         */
+        name: string;
+
+        /**
+         * The input with which to call the tool.
+         */
+        input: object;
+
+        /**
+         * Create a new LanguageModelToolCallPart.
+         *
+         * @param callId The ID of the tool call.
+         * @param name The name of the tool to call.
+         * @param input The input with which to call the tool.
+         */
+        constructor(callId: string, name: string, input: object);
+    }
+
+    /**
+     * The result of a tool call. This is the counterpart of a {@link LanguageModelToolCallPart tool call} and
+     * it can only be included in the content of a User message
+     * @stubbed
+     */
+    export class LanguageModelToolResultPart {
+        /**
+         * The ID of the tool call.
+         *
+         * *Note* that this should match the {@link LanguageModelToolCallPart.callId callId} of a tool call part.
+         */
+        callId: string;
+
+        /**
+         * The value of the tool result.
+         */
+        content: (LanguageModelTextPart | LanguageModelPromptTsxPart | unknown)[];
+
+        /**
+         * @param callId The ID of the tool call.
+         * @param content The content of the tool result.
+         */
+        constructor(callId: string, content: (LanguageModelTextPart | LanguageModelPromptTsxPart | unknown)[]);
+    }
+
+    /**
+     * A language model response part containing a piece of text, returned from a {@link LanguageModelChatResponse}.
+     * @stubbed
+     */
+    export class LanguageModelTextPart {
+        /**
+         * The text content of the part.
+         */
+        value: string;
+
+        /**
+         * Construct a text part with the given content.
+         * @param value The text content of the part.
+         */
+        constructor(value: string);
+    }
+
+    /**
+     * A language model response part containing a PromptElementJSON from `@vscode/prompt-tsx`.
+     * @see {@link LanguageModelToolResult}
+     * @stubbed
+     */
+    export class LanguageModelPromptTsxPart {
+        /**
+         * The value of the part.
+         */
+        value: unknown;
+
+        /**
+         * Construct a prompt-tsx part with the given content.
+         * @param value The value of the part, the result of `renderPromptElementJSON` from `@vscode/prompt-tsx`.
+         */
+        constructor(value: unknown);
+    }
+
+    /**
+     * A result returned from a tool invocation. If using `@vscode/prompt-tsx`, this result may be rendered using a `ToolResult`.
+     * @stubbed
+     */
+    export class LanguageModelToolResult {
+        /**
+         * A list of tool result content parts. Includes `unknown` becauses this list may be extended with new content types in
+         * the future.
+         * @see {@link lm.invokeTool}.
+         */
+        content: (LanguageModelTextPart | LanguageModelPromptTsxPart | unknown)[];
+
+        /**
+         * Create a LanguageModelToolResult
+         * @param content A list of tool result content parts
+         */
+        constructor(content: (LanguageModelTextPart | LanguageModelPromptTsxPart)[]);
+    }
+
+    /**
+     * A token that can be passed to {@link lm.invokeTool} when invoking a tool inside the context of handling a chat request.
+     */
+    export type ChatParticipantToolToken = never;
+
+    /**
+     * Options provided for tool invocation.
+     * @stubbed
+     */
+    export interface LanguageModelToolInvocationOptions<T> {
+        /**
+         * An opaque object that ties a tool invocation to a chat request from a {@link ChatParticipant chat participant}.
+         *
+         * The _only_ way to get a valid tool invocation token is using the provided {@link ChatRequest.toolInvocationToken toolInvocationToken}
+         * from a chat request. In that case, a progress bar will be automatically shown for the tool invocation in the chat response view, and if
+         * the tool requires user confirmation, it will show up inline in the chat view.
+         *
+         * If the tool is being invoked outside of a chat request, `undefined` should be passed instead, and no special UI except for
+         * confirmations will be shown.
+         *
+         * *Note* that a tool that invokes another tool during its invocation, can pass along the `toolInvocationToken` that it received.
+         */
+        toolInvocationToken: ChatParticipantToolToken | undefined;
+
+        /**
+         * The input with which to invoke the tool. The input must match the schema defined in
+         * {@link LanguageModelToolInformation.inputSchema}
+         */
+        input: T;
+
+        /**
+         * Options to hint at how many tokens the tool should return in its response, and enable the tool to count tokens
+         * accurately.
+         */
+        tokenizationOptions?: LanguageModelToolTokenizationOptions;
+    }
+
+    /**
+     * Options related to tokenization for a tool invocation.
+     * @stubbed
+     */
+    export interface LanguageModelToolTokenizationOptions {
+        /**
+         * If known, the maximum number of tokens the tool should emit in its result.
+         */
+        tokenBudget: number;
+
+        /**
+         * Count the number of tokens in a message using the model specific tokenizer-logic.
+         * @param text A string.
+         * @param token Optional cancellation token.  See {@link CancellationTokenSource} for how to create one.
+         * @returns A thenable that resolves to the number of tokens.
+         */
+        countTokens(text: string, token?: CancellationToken): Thenable<number>;
+    }
+
+    /**
+     * Information about a registered tool available in {@link lm.tools}.
+     * @stubbed
+     */
+    export interface LanguageModelToolInformation {
+        /**
+         * A unique name for the tool.
+         */
+        readonly name: string;
+
+        /**
+         * A description of this tool that may be passed to a language model.
+         */
+        readonly description: string;
+
+        /**
+         * A JSON schema for the input this tool accepts.
+         */
+        readonly inputSchema: object | undefined;
+
+        /**
+         * A set of tags, declared by the tool, that roughly describe the tool's capabilities. A tool user may use these to filter
+         * the set of tools to just ones that are relevant for the task at hand.
+         */
+        readonly tags: readonly string[];
+    }
+
+    /**
+     * Options for {@link LanguageModelTool.prepareInvocation}.
+     * @stubbed
+     */
+    export interface LanguageModelToolInvocationPrepareOptions<T> {
+        /**
+         * The input that the tool is being invoked with.
+         */
+        input: T;
+    }
+
+    /**
+     * A tool that can be invoked by a call to a {@link LanguageModelChat}.
+     * @stubbed
+     */
+    export interface LanguageModelTool<T> {
+        /**
+         * Invoke the tool with the given input and return a result.
+         *
+         * The provided {@link LanguageModelToolInvocationOptions.input} has been validated against the declared schema.
+         */
+        invoke(options: LanguageModelToolInvocationOptions<T>, token: CancellationToken): ProviderResult<LanguageModelToolResult>;
+
+        /**
+         * Called once before a tool is invoked. It's recommended to implement this to customize the progress message that appears
+         * while the tool is running, and to provide a more useful message with context from the invocation input. Can also
+         * signal that a tool needs user confirmation before running, if appropriate.
+         *
+         * * *Note 1:* Must be free of side-effects.
+         * * *Note 2:* A call to `prepareInvocation` is not necessarily followed by a call to `invoke`.
+         */
+        prepareInvocation?(options: LanguageModelToolInvocationPrepareOptions<T>, token: CancellationToken): ProviderResult<PreparedToolInvocation>;
+    }
+
+    /**
+     * When this is returned in {@link PreparedToolInvocation}, the user will be asked to confirm before running the tool. These
+     * messages will be shown with buttons that say "Continue" and "Cancel".
+     * @stubbed
+     */
+    export interface LanguageModelToolConfirmationMessages {
+        /**
+         * The title of the confirmation message.
+         */
+        title: string;
+
+        /**
+         * The body of the confirmation message.
+         */
+        message: string | MarkdownString;
+    }
+
+    /**
+     * The result of a call to {@link LanguageModelTool.prepareInvocation}.
+     * @stubbed
+     */
+    export interface PreparedToolInvocation {
+        /**
+         * A customized progress message to show while the tool runs.
+         */
+        invocationMessage?: string;
+
+        /**
+         * The presence of this property indicates that the user should be asked to confirm before running the tool. The user
+         * should be asked for confirmation for any tool that has a side-effect or may potentially be dangerous.
+         */
+        confirmationMessages?: LanguageModelToolConfirmationMessages;
+    }
+
+    /**
+     * A reference to a tool that the user manually attached to their request, either using the `#`-syntax inline, or as an
+     * attachment via the paperclip button.
+     * @stubbed
+     */
+    export interface ChatLanguageModelToolReference {
+        /**
+         * The tool name. Refers to a tool listed in {@link lm.tools}.
+         */
+        readonly name: string;
+
+        /**
+         * The start and end index of the reference in the {@link ChatRequest.prompt prompt}. When undefined, the reference was
+         * not part of the prompt text.
+         *
+         * *Note* that the indices take the leading `#`-character into account which means they can be used to modify the prompt
+         * as-is.
+         */
+        readonly range?: [start: number, end: number];
     }
 
     /**

package/src/theia.proposed.mappedEditsProvider.d.ts

@@ -35,6 +35,7 @@ export module '@theia/plugin' {
     export interface ConversationResponse {
         readonly type: 'response';
         readonly message: string;
+        readonly result?: ChatResult;
         readonly references?: DocumentContextItem[];
     }
 
@@ -69,7 +70,7 @@ export module '@theia/plugin' {
     }
 
     export interface MappedEditsRequest {
-        readonly codeBlocks: { code: string; resource: Uri }[];
+        readonly codeBlocks: { code: string; resource: Uri; markdownBeforeBlock?: string }[];
         // for every prior response that contains codeblocks, make sure we pass the code as well as the resources based on the reported codemapper URIs
         readonly conversation: (ConversationRequest | ConversationResponse)[];
     }