tom_vscode_scripting_api #

Tom VS Code — part of the Tom Framework by Peter Nicolai Alexis Kyaw. Licensed BSD-3-Clause. See LICENSE.

Drive a running VS Code window from Dart. A typed, bridge-agnostic client for the Tom AI VS Code extension: open files, run commands, query the language model, stream an Anthropic Agent SDK session, and reach the extension's own features — all over a local socket, from a plain Dart program or a *.d4rt.dart script.

Overview #

The Tom AI extension hosts a CLI Integration Server: a JSON-RPC server that exposes the editor's capabilities to out-of-process clients. tom_vscode_scripting_api is the Dart client for that server. Anything the extension can do inside the editor host becomes a typed Dart call.

It exposes three families of API behind one connection:

VS Code scripting — the editor mirrored as Dart (window, workspace, commands, extensions, lm, chat) plus the batteries-included VsCodeHelper.
Anthropic Agent SDK — a 1:1 Dart mirror of the Agent SDK: streaming query(), in-process Dart tools, and a canUseTool permission callback.
Extension features — the Tom AI extension's own subsystems (todos, the prompt queue, timed requests, documents, workspace metadata, tools, send-to-chat) as static-method classes.

The package is standalone (zero runtime dependencies) and bridge-agnostic: every API talks to an abstract VSCodeAdapter, so the same surface is testable against fakes.

Installation #

# pubspec.yaml
dependencies:
  tom_vscode_scripting_api: ^1.1.0

dart pub add tom_vscode_scripting_api

No native dependencies; pure Dart, SDK ^3.10.4.

Features #

VS Code scripting #

API	What it does
`VSCode`	Root singleton — version, env, clipboard, external URIs; owns the namespaces.
`window` (`VSCodeWindow`)	Messages, quick picks, input boxes, editors, output channels, status bar, terminals, file dialogs.
`workspace` (`VSCodeWorkspace`)	Folders, file finding, documents, host-side file system, configuration.
`commands` (`VSCodeCommands`)	Execute/register commands; `VSCodeCommonCommands` named constants.
`extensions` (`VSCodeExtensions`)	Query, activate, and read exports of installed extensions.
`lm` (`VSCodeLanguageModel`)	Select chat models (Copilot et al.), send requests, count tokens, register/invoke LM tools.
`chat` (`VSCodeChat`)	Register a chat participant whose handler runs in your Dart process.
`VsCodeHelper`	All-static convenience layer — Dart/Flutter tooling, Copilot prompts, editor edits, `VsProgress`, `FileBatch`.

Anthropic Agent SDK #

API	What it does
`AgentSdkClient`	`query()` → streaming `AgentQuery`; `collectQuery()` → `List<SdkMessage>`.
`Options`	Full Agent SDK option surface (model, tools, `maxTurns`, `permissionMode`, sessions, sub-agents, thinking…).
`SdkMessage` (sealed)	Raw-preserving typed message stream (`SdkAssistantMessage`, `SdkResultMessage`, …).
`SdkMcpTool` / `McpSdkServerConfig`	In-process Dart tools the agent can call.
`canUseTool` / `PermissionResult`	Per-call permission callback running in your process.

Extension features #

API	What it does
`AiPromptApi`	Run a prompt through the configured local LLM; manage profiles and models.
`AiConversationApi`	Drive the multi-turn bot-conversation engine.
`TomTodoApi`	CRUD over quest / workspace / session todos.
`TomQueueApi`	Full control of the multi-transport prompt queue.
`TomTimedApi`	Create and manage scheduled prompts; control the timer engine.
`TomDocumentApi`	Generic document store + typed Tom-folder accessors.
`TomWorkspaceApi`	Workspace info, projects, quests, the active quest, chat variables.
`TomToolsApi`	Invoke registered tools; fetch tools JSON for prompt injection.
`TomChatApi`	Send a prompt to the active chat target (Anthropic or Copilot).

Bridge transport #

Type	What it does
`VSCodeAdapter`	Abstract contract — `sendRequest(method, params)`. Everything routes through it.
`VSCodeBridgeClient`	Owns the socket; JSON-RPC 2.0, length-prefixed TCP, notifications + callbacks.
`VSCodeBridgeAdapter`	Wraps a connected client as a `VSCodeAdapter`.
`LazyVSCodeBridgeAdapter`	Same, but connects on first use — ideal for scripts.
`connectToWorkspace` / `findBridgePortForWorkspace` / `scanBridgePorts`	Discovery helpers — resolve the right window by the workspace it has open.

Quick start #

First, in the target VS Code window, run "DS: Start Tom CLI Integration Server" (Command Palette). Then, from Dart:

import 'package:tom_vscode_scripting_api/tom_vscode_scripting_api.dart';

Future<void> main() async {
  // Resolve the window by the workspace it has open, connect, and promote the
  // adapter to the VSCode singleton.
  await connectToWorkspace('tom_agent_container', initializeVSCode: true);

  final version = await VSCode.instance.getVersion();
  await VSCode.instance.window.showInformationMessage('Connected to VS Code $version');
  print('VS Code version: $version'); // e.g. VS Code version: 1.99.0
}

Example projects #

Runnable, self-contained samples live under example/, ordered as a learning path — each introduces one new capability on top of the last. Each sample is its own Dart subproject with a comprehensive README.

Sample	Introduces
`vscode_scripting_introduction_sample`	Connecting to a live window — messages, commands, workspace folders, reading and opening files. Start here.
`vscode_scripting_advanced_sample`	Editor edits, file batches, progress and pickers, the language model, and `VsCodeHelper`.
`vscode_agent_tools_sample`	The extension's own feature APIs — todos, the prompt queue, timed requests, documents, workspace metadata, tools, send-to-chat.
`vscode_agent_sdk_sample`	Streaming an Anthropic Agent SDK `query()` with `Options`, typed messages, in-process Dart `tool()`s, and `canUseTool`.

Usage #

Connect #

There are two ways to connect; pick by how many windows you run.

By port (single window):

import 'package:tom_vscode_scripting_api/script_globals.dart';

final adapter = LazyVSCodeBridgeAdapter(host: '127.0.0.1', port: 19900);
VSCode.initialize(adapter);

By workspace name (recommended for multi-window): the discovery helper scans the port range and matches the window by its open workspace.

final adapter = await connectToWorkspace('tom_agent_container', initializeVSCode: true);

Two initialisation styles #

Know which an API uses:

VS Code-namespace classes (VSCode, window, workspace, commands, extensions, lm, chat) read the VSCode singleton — call VSCode.initialize(adapter) once.
Extension-feature classes (TomTodoApi, TomQueueApi, AiPromptApi, …) are static-method classes — each needs <Class>.setAdapter(adapter).

final adapter = await connectToWorkspace('tom_agent_container');
VSCode.initialize(adapter);        // enables vscode / window / workspace / ...
TomTodoApi.setAdapter(adapter);    // enables TomTodoApi.*
TomQueueApi.setAdapter(adapter);   // enables TomQueueApi.*

Script the editor #

await window.setStatusBarMessage('Running analyzer…');
await commands.executeCommand('workbench.action.files.saveAll');

final diagnostics = await VsCodeHelper.getDiagnostics('lib/main.dart');
if (diagnostics.isEmpty) {
  await window.showInformationMessage('No problems found');
} else {
  await window.showWarningMessage('${diagnostics.length} problems');
}

→ VS Code scripting guide

Run an agent #

final bridge = VSCodeBridgeClient(host: '127.0.0.1', port: 19900);
await bridge.connect();
final client = AgentSdkClient(VSCodeBridgeAgentSdkTransport(bridge));

final query = client.query(
  prompt: 'Read lib/parser.dart and suggest three improvements',
  options: Options(model: 'claude-sonnet-4', maxTurns: 10),
);

await for (final m in query) {
  if (m is SdkAssistantMessage) {
    for (final b in m.content) {
      if (b is TextBlock) stdout.write(b.text);
    }
  }
}

The Agent SDK transport needs the raw VSCodeBridgeClient (not just the adapter) because it uses the bidirectional notification + callback channel. → Agent SDK guide

Drive the extension's features #

TomWorkspaceApi.setAdapter(adapter);
TomTodoApi.setAdapter(adapter);
TomChatApi.setAdapter(adapter);

await TomWorkspaceApi.setActiveQuest('vscode_extension');
final todos = await TomTodoApi.listQuestTodos('vscode_extension');

final reply = await TomChatApi.sendToChat(
  'I have ${todos.length} open todos. Suggest which to tackle first.',
);
print(reply.text);

→ Extension scripting guide

Architecture #

Three layers, lowest to highest. Everything above the adapter contract ultimately calls sendRequest; swap the adapter and the whole surface targets a different transport (or a test double).

┌───────────────────────────────────────────────────────────────┐
│  3. High-level APIs                                            │
│     VSCode / window / workspace / commands / extensions / lm   │
│     / chat   ·   VsCodeHelper   ·   AgentSdkClient             │
│     Ai*/Tom* extension-feature APIs                            │
├───────────────────────────────────────────────────────────────┤
│  2. Transport                                                 │
│     VSCodeBridgeAdapter / LazyVSCodeBridgeAdapter             │
│     VSCodeBridgeClient  (JSON-RPC 2.0, length-prefixed TCP)   │
├───────────────────────────────────────────────────────────────┤
│  1. Adapter contract                                          │
│     abstract VSCodeAdapter.sendRequest(method, params)        │
└───────────────────────────────────────────────────────────────┘
                              │  TCP socket  (port 19900–19909)
                              ▼
┌───────────────────────────────────────────────────────────────┐
│  Tom AI VS Code extension  —  CLI Integration Server          │
│  executes JS in the extension host (context.vscode global),   │
│  routes <area>.<op>Vce methods to extension features          │
└───────────────────────────────────────────────────────────────┘

VS Code-namespace calls are sent as an executeScriptVce request whose payload is JavaScript run in the extension host with a context.vscode global; the extension-feature APIs instead call dedicated <area>.<op>Vce methods (e.g. queue.listVce, localLlm.processVce). Server→client callbacks (Agent SDK chunks, canUseTool, chat handlers) are JSON-RPC requests pushed back over the same socket and routed by BridgeRequestDispatcher.

Key types #

Type	Role
`VSCodeAdapter`	Abstract request/response contract — the single seam every API depends on.
`VSCodeBridgeClient`	Socket owner: `connect`/`disconnect`, `sendRequest`, `notifications` stream, server→client handler registration.
`VSCodeBridgeAdapter` / `LazyVSCodeBridgeAdapter`	Adapt a client to `VSCodeAdapter`; the lazy variant connects on first use.
`VSCode`	Root singleton; gateway to the namespace classes after `initialize`.
`VsCodeHelper`	Static convenience layer over the namespaces.
`AgentSdkClient` / `AgentQuery`	Agent SDK entry; `AgentQuery extends StreamView<SdkMessage>` and adds `interrupt()`.
`AgentSdkTransport` / `VSCodeBridgeAgentSdkTransport`	Agent SDK seam and its socket-backed production implementation.
`Options`	Agent SDK configuration data class.
`SdkMessage` / `ContentBlock`	Sealed, raw-preserving message and content hierarchies.
`BridgeRequestDispatcher`	Routes server→client JSON-RPC requests to registered handlers.
`TomApi` / `AiApi`	Static-method extension-feature classes (each set up with `setAdapter`).

Ecosystem #

tom_vscode_scripting_api is the Dart client half of the Tom VS Code repo. The two halves meet only at the extension's JSON-RPC CLI Integration Server.

        ┌──────────────── inside the editor (TypeScript) ────────────────┐
        │  tom_vscode_extension  ◄── tom_vscode_shared / tom_vscode_workflow │
        │   · chat panels · prompt queue · tool registry · MCP server     │
        │   · CLI Integration Server  (JSON-RPC over TCP 19900–19909)     │
        └───────────────────────────────▲────────────────────────────────┘
                                         │  local socket
        ┌────────────────────── driving it (Dart) ───────────────────────┐
        │  tom_vscode_scripting_api  ──►  THIS PACKAGE (typed client)      │
        │  tom_vscode_bridge         ──►  Dart bridge server for CLI/d4rt  │
        └─────────────────────────────────────────────────────────────────┘

tom_vscode_extension — the extension that hosts the CLI Integration Server this client talks to.
tom_vscode_bridge — the Dart bridge server that builds on this package to give Tom CLI tools and d4rt scripts editor access.
Repository map — the whole Tom VS Code ecosystem at a glance.

Further documentation #

The full user guides live in doc/:

Guide	Covers
vscode_api_intro.md	Overview, architecture, connection model — start here.
vscode_api_vscode_scripting_guide.md	Scripting VS Code itself + `VsCodeHelper`.
vscode_api_anthropic_agent_sdk_guide.md	Scripting the Anthropic Agent SDK.
vscode_api_extension_scripting_guide.md	Scripting the extension's own features.

Status #


Version	1.1.0
Dart SDK	`^3.10.4`
Runtime dependencies	none (standalone)
Tests	85 passing across 8 suites (`dart test`)
License	BSD-3-Clause

License #

Part of the Tom Framework by Peter Nicolai Alexis Kyaw, BSD-3-Clause. See LICENSE.

tom_vscode_scripting_api 1.1.1
tom_vscode_scripting_api: ^1.1.1 copied to clipboard

Metadata

tom_vscode_scripting_api #

Overview #

Installation #

Features #

VS Code scripting #

Anthropic Agent SDK #

Extension features #

Bridge transport #

Quick start #

Example projects #

Usage #

Connect #

Two initialisation styles #

Script the editor #

Run an agent #

Drive the extension's features #

Architecture #

Key types #

Ecosystem #

Further documentation #

Status #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

More

tom_vscode_scripting_api 1.1.1 tom_vscode_scripting_api: ^1.1.1 copied to clipboard

Metadata

tom_vscode_scripting_api #

Overview #

Installation #

Features #

VS Code scripting #

Anthropic Agent SDK #

Extension features #

Bridge transport #

Quick start #

Example projects #

Usage #

Connect #

Two initialisation styles #

Script the editor #

Run an agent #

Drive the extension's features #

Architecture #

Key types #

Ecosystem #

Further documentation #

Status #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

More

tom_vscode_scripting_api 1.1.1
tom_vscode_scripting_api: ^1.1.1 copied to clipboard