script_globals library

Script Globals for VS Code Scripting API

This file provides global variable declarations for scripts. Import this file to get convenient access to VS Code API globals.

Usage

import 'package:tom_vscode_scripting_api/script_globals.dart';

void main() {
  // Now vscode, window, etc. are available
  vscode.window.showInformationMessage('Hello!');
}

Available Globals

Note

These globals require VSCode.initialize() to be called first.

Classes

AgentDefinition
A programmatic sub-agent definition. Mirrors AgentDefinition.
AgentQuery
A live Agent SDK query: a Stream<SdkMessage> plus control methods.
AgentSdkClient
Entry point mirroring the SDK's query() free function, bound to a AgentSdkTransport.
AgentSdkToolRegistry
Indexes the Dart ToolHandlers a query exposes and dispatches incoming agentSdk.toolCall requests to them.
AgentSdkTransport
Transport seam for streaming Agent SDK queries.
AiConversationApi
AI Conversation API — bot conversation orchestration.
AiModelConfig
An Ollama model configuration.
AiModelsResult
Result of listing available models, including the effective default.
AiPromptApi
AI Prompt API — local LLM prompt expansion.
AiPromptProfile
A prompt expander profile.
AiPromptResult
Result of a prompt expansion via AiPromptApi.process.
AiTokenStats
Token usage statistics from a local Ollama model call.
BridgeRequestDispatcher
Routes incoming server→client requests to registered handlers and writes their replies through an injected sink.
CallToolResult
The result a ToolHandler returns. Mirrors MCP CallToolResult.
CanUseToolContext
Context passed to a CanUseTool callback. Mirrors the SDK's { suggestions?, signal } argument; the payload is kept opaque (raw) until the reverse-RPC wiring (todos #4–#6) gives it structure.
ChatContext
Context for a chat request including conversation history
ChatErrorDetails
Error details for a failed chat request
ChatParticipant
A chat participant
ChatPromptReference
A reference in a chat prompt
ChatRequest
A chat request from the user
ChatResponseStream
A stream for sending responses back to the chat
ChatResult
Result of handling a chat request
ChatVariable
Chat variable value.
ChatVariableListResult
Result of listing chat variables.
ContentBlock
A content block inside an assistant or user message.
ConversationActionResult
Result of a stop/halt/continue/addInfo operation.
ConversationConfig
Bot conversation configuration (resolved from send_to_chat.json).
ConversationExchange
A single exchange (turn) in a bot conversation.
ConversationLog
Conversation log retrieved from disk.
ConversationProfile
A named bot conversation profile.
ConversationResult
Result of starting a bot conversation via AiConversationApi.start.
ConversationStatus
Current status of a bot conversation.
CopilotResponse
Response from Copilot in a bot conversation exchange.
DocumentContent
Content of a document.
DocumentInfo
Metadata about a document file.
DocumentListResult
Result of listing documents.
Extension
Represents a VS Code extension
FileBatch
File batch processor
FileSystemWatcherOptions
File system watcher options
FollowUpInput
Input for adding a follow-up prompt to a queue item.
GuidelineInfo
Guideline document info.
GuidelineListResult
Result of listing guidelines.
HelperLogging
Logging control for VsCodeHelper
InputBoxOptions
Input box options
LanguageModelChat
Represents a language model for chat requests
LanguageModelChatMessage
A message in a chat conversation
LanguageModelChatResponse
Response from a language model chat request
LanguageModelToolInformation
Information about a registered tool
LanguageModelToolResult
Tool result from language model
LazyVSCodeBridgeAdapter
A lazy-connecting adapter that auto-connects on first use.
McpHttpServerConfig
An HTTP MCP server. Mirrors McpHttpServerConfig.
McpSdkServerConfig
An in-process ("sdk") MCP server. Mirrors McpSdkServerConfigWithInstance, but carries a serializable descriptor instead of a live McpServer (proposal §7.0.4): the extension reconstructs the real instance.
McpServerConfig
An MCP server configuration referenced from Options.mcpServers. Mirrors McpServerConfig (stdio / sse / http / sdk variants).
McpServerToolPolicy
Per-tool permission policy for a remote MCP server. Mirrors McpServerToolPolicy (permission_policy is snake_case on the wire).
McpSSEServerConfig
An SSE MCP server. Mirrors McpSSEServerConfig.
McpStdioServerConfig
A stdio MCP server. Mirrors McpStdioServerConfig.
MessageOptions
Message options
Options
Options for an Agent SDK query. Mirrors the SDK's Options type.
OutputFormat
Structured output configuration. Mirrors { type:'json_schema', schema }.
PermissionAllow
Allow result (behavior: 'allow').
PermissionDeny
Deny result (behavior: 'deny').
PermissionResult
The result returned by a CanUseTool callback. Mirrors PermissionResult (an allow/deny union).
PermissionRuleValue
A single tool-permission rule. Mirrors PermissionRuleValue.
PermissionUpdate
A permission-rule mutation. Mirrors PermissionUpdate (six variants).
PermissionUpdateDirectories
addDirectories / removeDirectories updates.
PermissionUpdateRules
addRules / replaceRules / removeRules updates.
PermissionUpdateSetMode
setMode update.
PluginConfig
A local plugin configuration. Mirrors SdkPluginConfig.
Position
Position in a text document
ProjectInfo
Information about a project in the workspace.
ProjectListResult
Result of listing projects.
QuestInfo
Information about a quest.
QuestListResult
Result of listing quests.
QueuedFollowUp
A follow-up prompt attached to a queue item.
QueuedPrompt
A queued prompt item.
QueueItemInput
Input for creating a new queue item.
QueueListResult
Result of listing queue items.
QuickPickItem
Quick pick item
Range
Range in a text document
ScheduledTime
A scheduled time slot.
SdkAssistantMessage
Mirrors SDKAssistantMessage (type: 'assistant').
SdkMcpTool
An in-process tool definition. Mirrors SdkMcpToolDefinition / the object built by tool().
SdkMessage
A single message yielded by an Agent SDK query stream.
SdkPartialAssistantMessage
Mirrors SDKPartialAssistantMessage (type: 'stream_event'), emitted only when includePartialMessages is set.
SdkResultMessage
Mirrors SDKResultMessage (type: 'result', success or error subtype).
SdkSystemEvent
Carrier for the long tail of type: 'system' events that are not init (e.g. compact_boundary, status, task_progress, rate_limit, …).
SdkSystemMessage
Mirrors SDKSystemMessage (type: 'system', subtype: 'init').
SdkUnknownMessage
Forward-compatible fallback for any top-level type this mirror does not model. Preserves the full payload in raw.
SdkUserMessage
Mirrors SDKUserMessage (type: 'user', incl. the replay variant).
Selection
Selection in a text editor
SendToChatResult
The outcome of a TomChatApi.sendToChat call.
SettingsInline
Inline settings.
SettingsPath
A path to a settings file.
SettingsRef
A settings reference. Mirrors string | Settings (a path or an inline map).
SingleTurnResult
Result of a single-turn Ollama→Copilot round-trip.
Skills
The skills selection. Mirrors string[] | 'all'.
SkillsAll
Enable all skills ('all').
SkillsList
An explicit list of skill names.
SystemPrompt
The system prompt. Mirrors string | string[] | { type:'preset', … }.
SystemPromptList
A multi-section system prompt (string array).
SystemPromptPreset
The Claude Code preset system prompt, optionally appended/trimmed.
SystemPromptText
A plain-string system prompt.
TaskBudget
A task budget. Mirrors { total }.
TerminalOptions
Terminal options
TextBlock
Mirrors a text content block.
TextDocument
Text document representation
TextEditor
Text editor representation
ThinkingAdaptive
Adaptive thinking — the model decides (type: 'adaptive').
ThinkingBlock
Mirrors a thinking content block.
ThinkingConfig
Extended-thinking configuration. Mirrors ThinkingConfig.
ThinkingDisabled
No extended thinking (type: 'disabled').
ThinkingEnabled
Fixed thinking budget (type: 'enabled').
TimedRequest
A timed request entry.
TimedRequestInput
Input for creating a new timed request.
TimedRequestListResult
Result of listing timed requests.
TodoFileListResult
Result of listing todo files.
TodoItem
A single TODO item.
TodoListResult
Result of listing todos.
TodoReference
Reference within a todo item.
TodoScope
Scope within a todo item.
TomChatApi
Scripting access to the Tom extension's "Send to Chat" transport.
TomDocumentApi
API for accessing workspace documents.
TomQueueApi
API for managing the prompt queue.
TomTimedApi
API for managing timed/scheduled requests.
TomTodoApi
API for managing TODO items across quest, workspace, and session scopes.
TomToolsApi
Scripting access to the Tom extension's LLM tool registry.
TomWorkspaceApi
API for accessing workspace structure and configuration.
ToolDefinitionJson
An Anthropic-shaped tool definition: {name, description, input_schema}.
ToolResultBlock
Mirrors a tool_result content block.
ToolsClaudeCodePreset
The Claude Code default tool preset.
ToolsConfig
The tool selection. Mirrors string[] | { type:'preset', preset:'claude_code' }.
ToolsList
An explicit list of tool names.
ToolUseBlock
Mirrors a tool_use content block.
TrailEntry
Trail entry (prompt/answer pair).
TrailListResult
Result of listing trail entries.
UnknownBlock
Forward-compatible fallback for any content block type this mirror does not model (redacted_thinking, server_tool_use, image, …).
VSCode
Main VS Code API wrapper class Provides unified access to all VS Code APIs through Dart
VSCodeAdapter
Abstract interface for sending requests to VS Code
VSCodeBridgeAdapter
Implementation of VSCodeAdapter using VSCodeBridgeClient.
VSCodeBridgeAgentSdkTransport
Production AgentSdkTransport backed by a VSCodeBridgeClient.
VSCodeBridgeClient
Client for communicating with VS Code VS Code Bridge.
VSCodeBridgeResult
Result of a VS Code bridge command execution.
VSCodeChat
Chat API - Create and manage chat participants
VSCodeCommands
Wrapper for vscode.commands API Provides access to VS Code command system
VSCodeCommonCommands
Common VS Code commands
VSCodeExtensions
Wrapper for vscode.extensions API Provides access to VS Code extensions management
VsCodeHelper
Helper class for VS Code API operations in scripts
VSCodeLanguageModel
Language Model API - Access to GitHub Copilot and other language models
VSCodeUri
Represents a URI in VS Code
VSCodeWindow
Wrapper for vscode.window API Provides access to window-related functionality (UI, messages, editors, etc.)
VSCodeWorkspace
Wrapper for vscode.workspace API Provides access to workspace-related functionality
VsProgress
Progress indicator helper
WorkspaceFolder
Represents a workspace folder
WorkspaceInfo
Workspace metadata.

Enums

ConversationMode
Conversation mode — who talks to whom.
DiagnosticSeverity
Diagnostic severity
DocumentFolder
Type of document folder.
EffortLevel
Reasoning-effort level. Mirrors EffortLevel.
HistoryMode
History mode — how much conversation history is passed to the local model.
PermissionBehavior
Behaviour applied by a permission rule. Mirrors PermissionBehavior.
PermissionDecisionClassification
Classification of a permission decision. Mirrors PermissionDecisionClassification (snake_case wire values).
PermissionMode
Controls how tool executions are handled. Mirrors PermissionMode (six values; default is spelled PermissionMode.default_ in Dart).
PermissionUpdateDestination
Where a permission update is persisted. Mirrors PermissionUpdateDestination.
ProjectType
Type of project detected in the workspace.
QueuedPromptStatus
Status of a queued prompt.
QueuedPromptType
Type of a queued prompt.
ScheduleMode
Schedule mode for timed requests.
SettingSource
Where the agent loads filesystem settings from. Mirrors SettingSource.
TimedRequestStatus
Status of a timed request entry.
TodoPriority
Priority of a todo item.
TodoStatus
Status of a todo item.

Constants

defaultVSCodeBridgePort → const int
Default (and lowest) port for the VS Code CLI Integration Server.
maxVSCodeBridgePort → const int
Highest port in the VS Code CLI Integration Server range.

Properties

chat → VSCodeChat
VS Code chat API.
no setter
commands → VSCodeCommands
VS Code commands API.
no setter
extensions → VSCodeExtensions
VS Code extensions API.
no setter
lm → VSCodeLanguageModel
VS Code language model API.
no setter
vscode → VSCode
Main VS Code API entry point.
no setter
window → VSCodeWindow
VS Code window API.
no setter
workspace → VSCodeWorkspace
VS Code workspace API.
no setter

Functions

connectToWorkspace(String name, {String host = '127.0.0.1', int minPort = defaultVSCodeBridgePort, int maxPort = maxVSCodeBridgePort, BridgePortProbe probe = _defaultProbe, BridgeIdentityFetcher fetchIdentity = fetchBridgeWorkspaceName, bool initializeVSCode = false, BridgeAdapterFactory adapterFactory = _defaultAdapterFactory}) → Future<LazyVSCodeBridgeAdapter>
Resolves the bridge port for the workspace named name (via findBridgePortForWorkspace) and returns a connected adapter bound to it.
dispatchCanUseTool(CanUseTool callback, Map<String, dynamic> params) → Future<Map<String, dynamic>>
Invokes callback for an incoming agentSdk.canUseTool request and returns its PermissionResult as wire JSON.
fetchBridgeWorkspaceName(String host, int port) → Future<String?>
Default BridgeIdentityFetcher — connects to the bridge on host:port, issues a workspace.getInfoVce window-identity handshake, and derives the workspace name from the result. Returns null if the bridge cannot be reached or yields no identifiable workspace.
findBridgePortForWorkspace(String name, {String host = '127.0.0.1', int minPort = defaultVSCodeBridgePort, int maxPort = maxVSCodeBridgePort, BridgePortProbe probe = _defaultProbe, BridgeIdentityFetcher fetchIdentity = fetchBridgeWorkspaceName}) → Future<int>
Scans the CLI bridge port range for the window whose workspace matches name and returns its port.
normalizeWorkspaceName(String value) → String
Normalises a workspace name for comparison: trims whitespace, drops a trailing .code-workspace extension, and strips VS Code's " (Workspace)" multi-root suffix.
scanBridgePorts({String host = '127.0.0.1', int minPort = defaultVSCodeBridgePort, int maxPort = maxVSCodeBridgePort, BridgePortProbe probe = _defaultProbe, BridgeIdentityFetcher fetchIdentity = fetchBridgeWorkspaceName}) → Future<Map<int, String>>
Scans the CLI bridge port range and returns a port → workspace table for every responsive bridge.

Typedefs

BridgeAdapterFactory = LazyVSCodeBridgeAdapter Function(String host, int port)
Creates a port-bound LazyVSCodeBridgeAdapter for a resolved bridge.
BridgeIdentityFetcher = Future<String?> Function(String host, int port)
Fetches the workspace identity name reported by the bridge on host:port, or null if the bridge does not answer / has no identifiable workspace.
BridgePortProbe = Future<bool> Function(String host, int port)
Probes whether a bridge is listening on host:port.
BridgeRequestHandler = FutureOr<Object?> Function(Map<String, dynamic> params)
A handler for an incoming server→client request method. Receives the request params and returns the JSON-encodable result (sync or async).
CanUseTool = Future<PermissionResult> Function(String toolName, Map<String, dynamic> input, CanUseToolContext context)
Tool-approval callback. Mirrors CanUseTool.
ChatRequestHandler = Future<ChatResult?> Function(ChatRequest request, ChatContext context, ChatResponseStream stream)
Chat request handler callback
ToolHandler = Future<CallToolResult> Function(Map<String, dynamic> args)
A tool callback that runs in Dart. Mirrors the handler passed to tool().

Exceptions / Errors

AgentSdkQueryException
Thrown into an AgentQuery's stream when the extension reports a query failure via an error chunk.
BridgeWorkspaceNotFoundException
Thrown by findBridgePortForWorkspace when no responsive bridge in the scanned range has the requested workspace open.