Assistant: Add Inspect Variables tool (#7662)

Today, Assistant is provided with a summary of the currently active
variables, but it must use ad-hoc R or Python code to get more
information on each variable.

This change adds a variable inspection tool to Assistant, which it can
use to look up variable details. It effectively gives the Assistant
access to the Variables pane, so it can expand any value in the tree and
see what's inside it, and uses the variables comm just like the UI does.

<img width="406" alt="image"
src="https://github.com/user-attachments/assets/9e1a3ec8-f760-4179-9d71-7d3c5fac60ca"
/>

Addresses #7081

### QA Notes

- Assistant will still run R or Python code to get information on
variables in some cases. This tool lets Assistant look inside variables,
but it can't answer questions like "what is the largest value in the
first column".
- Additional work is needed to let Assistant see into data objects
without running R/Python code and scraping the output. That work is
tracked in #7114.

Tests: `@:variables` `@:assistant`

Author: jmcphers

extensions/positron-assistant/package.json

@@ -189,6 +189,36 @@
           "positron-assistant"
         ]
       },
+      {
+        "name": "inspectVariables",
+        "displayName": "Inspect Variables",
+        "modelDescription": "Inspect one or more variables in a console session, listing their child values, if any. Can be used to list the columns in a dataframe, the items in a column or array, or the elements of a list. Returns an array containing an array of children for each variable in the request. IMPORTANT: always use the access_key (even if it is a JSON string), NOT the display_name to refer to a variable. Example: for a session with identifier s-123 and variables [ { display_name: 'df', access_key: 'df-key' }, { 'display_name: 'foo', 'access_key': 'foo-key' } ], a request could be look like { 'sessionIdentifier': 's-123', 'accessKeys': [ ['df-key'], ['foo-key', 'bar-key'] ] }; the response would be an array of arrays, where each inner array contains the child variables of the corresponding variable in the request. The first inner array would contain the columns of the dataframe, and the second inner array would contain the elements of the list 'bar' inside the list 'foo'. Cannot be called when there is no session (the session identifier is empty or not defined). Can be called without any access keys to list all root-level variables in the session.",
+        "canBeReferencedInPrompt": false,
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "sessionIdentifier": {
+              "type": "string",
+              "description": "The identifier of the console session to inspect."
+            },
+            "accessKeys": {
+              "type": "array",
+              "description": "An array of the variables to inspect. Each entry is an array of access keys that represent the path to the variable to inspect.",
+              "items": {
+                "type": "array",
+                "description": "A list of access keys that identify a variable by specifying its path.",
+                "items": {
+                  "type": "string",
+                  "description": "An access key that uniquely identifies a variable among its siblings."
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "positron-assistant"
+        ]
+      },
       {
         "name": "getPlot",
         "displayName": "View active plot",

extensions/positron-assistant/src/tools.ts

@@ -13,6 +13,7 @@ export enum PositronAssistantToolName {
 	EditFile = 'vscode_editFile_internal',
 	ExecuteCode = 'executeCode',
 	GetPlot = 'getPlot',
+	InspectVariables = 'inspectVariables',
 	SelectionEdit = 'selectionEdit',
 }
 
@@ -250,6 +251,38 @@ export function registerAssistantTools(
 	});
 
 	context.subscriptions.push(getPlotTool);
+
+	const inspectVariablesTool = vscode.lm.registerTool<{ sessionIdentifier: string; accessKeys: Array<Array<string>> }>(PositronAssistantToolName.InspectVariables, {
+		/**
+		 * Called to inspect one or more variables in the current session.
+		 *
+		 * @param options The options for the tool invocation.
+		 * @param token The cancellation token.
+		 *
+		 * @returns A vscode.LanguageModelToolResult.
+		 */
+		invoke: async (options, token) => {
+
+			// If no session identifier is provided, return an empty array.
+			if (!options.input.sessionIdentifier || options.input.sessionIdentifier === 'undefined') {
+				return new vscode.LanguageModelToolResult([
+					new vscode.LanguageModelTextPart('[[]]')
+				]);
+			}
+
+			// Call the Positron API to get the session variables
+			const result = await positron.runtime.getSessionVariables(
+				options.input.sessionIdentifier,
+				options.input.accessKeys);
+
+			// Return the result as a JSON string to the model
+			return new vscode.LanguageModelToolResult([
+				new vscode.LanguageModelTextPart(JSON.stringify(result))
+			]);
+		}
+	});
+
+	context.subscriptions.push(inspectVariablesTool);
 }
 
 /**

extensions/vscode-api-tests/src/singlefolder-tests/positron/assistant.test.ts

@@ -0,0 +1,101 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (C) 2025 Posit Software, PBC. All rights reserved.
+ *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import 'mocha';
+import * as positron from 'positron';
+import * as vscode from 'vscode';
+import { assertNoRpcFromEntry } from '../../utils.js';
+import assert from 'assert';
+
+suite('positron API - ai', () => {
+
+	suiteSetup(async () => {
+		await vscode.extensions.getExtension('vscode.vscode-api-tests')?.activate();
+	});
+
+	teardown(async function () {
+		assertNoRpcFromEntry([positron, 'positron']);
+	});
+
+	test('getSupportedProviders returns providers', async () => {
+		const providers = await positron.ai.getSupportedProviders();
+		assert.ok(Array.isArray(providers), 'Providers should be an array');
+	});
+
+	test('getCurrentPlotUri returns expected type', async () => {
+		const plotUri = await positron.ai.getCurrentPlotUri();
+		assert.ok(plotUri === undefined || typeof plotUri === 'string',
+			'Plot URI should be either undefined or a string');
+	});
+
+	test('registerChatAgent handles valid agent data', async () => {
+		const agentData: positron.ai.ChatAgentData = {
+			id: 'test.agent',
+			name: 'Test Agent',
+			fullName: 'Test Chat Agent',
+			description: 'A test chat agent',
+			isDefault: false,
+			metadata: {
+				isSticky: true
+			},
+			slashCommands: [
+				{
+					name: 'test',
+					description: 'Run a test command',
+					isSticky: true
+				}
+			],
+			locations: [positron.PositronChatAgentLocation.Panel],
+			disambiguation: [
+				{
+					category: 'test',
+					description: 'Test category',
+					examples: ['example 1', 'example 2']
+				}
+			]
+		};
+
+		const disposable = await positron.ai.registerChatAgent(agentData);
+		assert.ok(disposable, 'Should return a valid disposable');
+		disposable.dispose();
+	});
+
+	test('getPositronChatContext returns valid context for request', async () => {
+		// Create a proper ChatRequest with required properties
+		// Using 'any' to bypass type checking as we're only testing getPositronChatContext
+		// which only uses the location property from the request
+		const request: Partial<vscode.ChatRequest> = {
+			prompt: 'test request',
+			command: 'ask',
+			references: [],
+			location: vscode.ChatLocation.Panel,
+			model: {
+				id: 'test-model',
+				name: 'Test Model',
+				vendor: 'test',
+				family: 'test-family',
+				version: '1.0.0',
+				capabilities: {
+					supportsImageToText: false,
+					supportsToolCalling: false
+				},
+				maxInputTokens: 2000,
+				sendRequest: async () => ({
+					stream: (async function* () { yield ''; })(),
+					text: (async function* () { yield ''; })()
+				}),
+				countTokens: async () => 0
+			}
+		};
+
+		const context = await positron.ai.getPositronChatContext(request as vscode.ChatRequest);
+
+		assert.ok(context, 'Context should be returned');
+		// Context may contain console, variables, shell, but these may be undefined
+		// depending on the current state, so we just check the type
+		assert.ok('console' in context || 'variables' in context || 'shell' in context,
+			'Context should have expected structure');
+	});
+});