VS Codeのエージェントモードを拡張するには、を試してください！

拡張機能開発におけるWebAssemblyの活用

2024年5月8日 Dirk Bäumer

Visual Studio Codeは、WebAssembly Execution Engine拡張機能を通じてWASMバイナリの実行をサポートしています。主な用途は、C/C++またはRustで書かれたプログラムをWebAssemblyにコンパイルし、これらのプログラムをVS Codeで直接実行することです。注目すべき例としては、Visual Studio Code for Educationがあり、これはこのサポートを利用してWeb版VS CodeでPythonインタープリタを実行しています。このブログ記事では、その実装方法について詳細な洞察が提供されています。

2024年1月、Bytecode AllianceはWASI 0.2プレビューを発表しました。WASI 0.2プレビューにおける主要な技術はコンポーネントモデルです。WebAssemblyコンポーネントモデルは、インターフェース、データ型、モジュール構成を標準化することで、WebAssemblyコンポーネントとそのホスト環境間の相互作用を合理化します。この標準化は、WIT（WASM Interface Type）ファイルの利用を通じて促進されます。WITファイルは、JavaScript/TypeScript拡張機能（ホスト）と、RustやC/C++などの別の言語でコーディングされた計算を実行するWebAssemblyコンポーネント間の相互作用を記述するのに役立ちます。

このブログ記事では、開発者がコンポーネントモデルを活用してWebAssemblyライブラリを拡張機能に統合する方法について概説します。私たちは3つのユースケースに焦点を当てます。(a) WebAssemblyを使用してライブラリを実装し、JavaScript/TypeScriptの拡張機能コードから呼び出す、(b) WebAssemblyコードからVS Code APIを呼び出す、(c) リソースを使用してステートフルなオブジェクトをWebAssemblyまたはTypeScriptコードでカプセル化および管理する方法を示す。

これらの例では、VS CodeとNodeJSに加えて、以下のツールの最新バージョンがインストールされている必要があります。rust compiler toolchain、wasm-tools、そしてwit-bindgenです。

また、L. Pereira氏とFastlyのLuke Wagner氏には、この記事に関する貴重なフィードバックをいただき、感謝申し上げます。

Rust製電卓

最初の例では、開発者がRustで書かれたライブラリをVS Code拡張機能に統合する方法を示します。前述のとおり、コンポーネントはWITファイルを使用して記述されます。この例では、ライブラリは加算、減算、乗算、除算などの単純な操作を実行します。対応するWITファイルは以下のとおりです。

package vscode:example;

interface types {
	record operands {
		left: u32,
		right: u32
	}

	variant operation {
		add(operands),
		sub(operands),
		mul(operands),
		div(operands)
	}
}
world calculator {
	use types.{ operation };

	export calc: func(o: operation) -> u32;
}

Rustツールwit-bindgenは、電卓用のRustバインディングを生成するために使用されます。このツールには2つの使用方法があります。

  • 実装ファイル内で直接バインディングを生成する手続き型マクロとして。この方法は標準的ですが、生成されたバインディングコードを検査できないという欠点があります。

  • コマンドラインツールとして、ディスク上にバインディングファイルを作成します。このアプローチは、以下のリソースの例におけるVS Code拡張機能サンプルリポジトリにあるコードで例示されています。

wit-bindgenツールを手続き型マクロとして使用する対応するRustファイルは、以下のようになります。

// Use a procedural macro to generate bindings for the world we specified in
// `calculator.wit`
wit_bindgen::generate!({
	// the name of the world in the `*.wit` input file
	world: "calculator",
});

しかし、Rustファイルをcargo build --target wasm32-unknown-unknownコマンドでWebAssemblyにコンパイルすると、エクスポートされたcalc関数の実装が不足しているためコンパイルエラーが発生します。以下にcalc関数の簡単な実装を示します。

// Use a procedural macro to generate bindings for the world we specified in
// `calculator.wit`
wit_bindgen::generate!({
	// the name of the world in the `*.wit` input file
	world: "calculator",
});

struct Calculator;

impl Guest for Calculator {

    fn calc(op: Operation) -> u32 {
		match op {
			Operation::Add(operands) => operands.left + operands.right,
			Operation::Sub(operands) => operands.left - operands.right,
			Operation::Mul(operands) => operands.left * operands.right,
			Operation::Div(operands) => operands.left / operands.right,
		}
	}
}

// Export the Calculator to the extension code.
export!(Calculator);

ファイルの最後にあるexport!(Calculator);文は、WebAssemblyコードからCalculatorをエクスポートし、拡張機能がAPIを呼び出せるようにします。

wit2tsツールは、VS Code拡張機能内でWebAssemblyコードと対話するために必要なTypeScriptバインディングを生成するために使用されます。このツールは、主に以下の理由により、VS Code拡張機能アーキテクチャの特定の要件を満たすためにVS Codeチームによって開発されました。

  • VS Code APIは、拡張機能ホストワーカー内でのみアクセス可能です。拡張機能ホストワーカーからスポーンされた追加のワーカーは、VS Code APIへのアクセス権を持たず、これはNodeJSやブラウザのような環境とは対照的です。これらの環境では、各ワーカーは通常、ほとんどすべてのランタイムAPIにアクセスできます。
  • 複数の拡張機能が同じ拡張機能ホストワーカーを共有します。拡張機能は、そのワーカー上で長時間にわたる同期計算を実行しないようにする必要があります。

これらのアーキテクチャ要件は、VS Code向けWASI Preview 1を実装した時点ですでに存在していました。しかし、初期の実装は手書きでした。コンポーネントモデルのより広範な採用を予測し、VS Code固有のホスト実装とコンポーネントの統合を容易にするツールを開発しました。

コマンドwit2ts --outDir ./src ./witを実行すると、srcフォルダにcalculator.tsファイルが生成され、WebAssemblyコード用のTypeScriptバインディングが含まれます。これらのバインディングを利用する簡単な拡張機能は次のようになります。

import * as vscode from 'vscode';
import { WasmContext, Memory } from '@vscode/wasm-component-model';

// Import the code generated by wit2ts
import { calculator, Types } from './calculator';

export async function activate(context: vscode.ExtensionContext): Promise<void> {
  // The channel for printing the result.
  const channel = vscode.window.createOutputChannel('Calculator');
  context.subscriptions.push(channel);

  // Load the Wasm module
  const filename = vscode.Uri.joinPath(
    context.extensionUri,
    'target',
    'wasm32-unknown-unknown',
    'debug',
    'calculator.wasm'
  );
  const bits = await vscode.workspace.fs.readFile(filename);
  const module = await WebAssembly.compile(bits);

  // The context for the WASM module
  const wasmContext: WasmContext.Default = new WasmContext.Default();

  // Instantiate the module
  const instance = await WebAssembly.instantiate(module, {});
  // Bind the WASM memory to the context
  wasmContext.initialize(new Memory.Default(instance.exports));

  // Bind the TypeScript Api
  const api = calculator._.exports.bind(
    instance.exports as calculator._.Exports,
    wasmContext
  );

  context.subscriptions.push(
    vscode.commands.registerCommand('vscode-samples.wasm-component-model.run', () => {
      channel.show();
      channel.appendLine('Running calculator example');
      const add = Types.Operation.Add({ left: 1, right: 2 });
      channel.appendLine(`Add ${api.calc(add)}`);
      const sub = Types.Operation.Sub({ left: 10, right: 8 });
      channel.appendLine(`Sub ${api.calc(sub)}`);
      const mul = Types.Operation.Mul({ left: 3, right: 7 });
      channel.appendLine(`Mul ${api.calc(mul)}`);
      const div = Types.Operation.Div({ left: 10, right: 2 });
      channel.appendLine(`Div ${api.calc(div)}`);
    })
  );
}

上記のコードをWeb版VS Codeでコンパイルして実行すると、Calculatorチャンネルに以下の出力が生成されます。

この例の全ソースコードは、VS Code拡張機能サンプルリポジトリで確認できます。

@vscode/wasm-component-modelの内部

wit2tsツールによって生成されたソースコードを検査すると、@vscode/wasm-component-model npmモジュールへの依存関係が明らかになります。このモジュールは、コンポーネントモデルの標準ABIのVS Code実装として機能し、対応するPythonコードから着想を得ています。このブログ記事を理解するためにコンポーネントモデルの内部を把握する必要はありませんが、特にJavaScript/TypeScriptとWebAssemblyコード間でデータがどのように渡されるかに関して、その動作についていくつか説明します。

wit-bindgenやjcoなどの他のツールがWITファイルのバインディングを生成するのとは異なり、wit2tsはメタモデルを作成し、それを使用してさまざまなユースケース向けに実行時にバインディングを生成できます。この柔軟性により、VS Codeでの拡張機能開発のアーキテクチャ要件を満たすことができます。このアプローチを使用することで、バインディングを「promisify」し、ワーカーでWebAssemblyコードを実行できるようになります。私たちはこのメカニズムを使用して、VS Code向けのWASI 0.2プレビューを実装しています。

バインディングを生成する際に、関数がcalculator._.imports.create（アンダースコアに注意）のような名前で参照されていることに気づいたかもしれません。WITファイル内のシンボルとの名前の衝突を避けるため（例えば、importsという名前の型定義がある可能性があります）、API関数は_名前空間に配置されます。メタモデル自体は$名前空間にあります。したがって、calculator.$.exports.calcはエクスポートされたcalc関数のメタデータを表します。

上記の例では、calc関数に渡されるadd操作のパラメータは、操作コード、左の値、右の値の3つのフィールドで構成されます。コンポーネントモデルの標準ABIによれば、引数は値渡しされます。また、データがどのようにシリアライズされ、WebAssembly関数に渡され、反対側でデシリアライズされるかも規定されています。このプロセスにより、JavaScriptヒープ上と線形WebAssemblyメモリ内にそれぞれ1つずつ、2つの操作オブジェクトが生成されます。以下の図がこれを示しています。

Diagram illustrating how parameters are passed.

以下の表は、利用可能なWIT型、VS Codeコンポーネントモデル実装におけるJavaScriptオブジェクトへのマッピング、および使用される対応するTypeScript型を示しています。

WIT JavaScript TypeScript
u8 number type u8 = number;
u16 number type u16 = number;
u32 number type u32 = number;
u64 bigint type u64 = bigint;
s8 number type s8 = number;
s16 number type s16 = number;
s32 number type s32 = number;
s64 bigint type s64 = bigint;
float32 number type float32 = number;
float64 number type float64 = number;
bool boolean boolean
string string string
char string[0] string
record object literal type declaration
list<T> [] Array<T>
tuple<T1, T2> [] [T1, T2]
enum string values string enum
flags number bigint
variant object literal discriminated union
option<T> variable ? and (T | undefined)
result<ok, err> Exception or object literal Exception or result type

コンポーネントモデルが低レベルの（Cスタイルの）ポインタをサポートしていないことに注意することが重要です。そのため、オブジェクトグラフや再帰的なデータ構造を渡すことはできません。この点では、JSONと同じ制限を共有しています。データのコピーを最小限に抑えるために、コンポーネントモデルはリソースの概念を導入しており、これについてはこのブログ記事の今後のセクションで詳しく説明します。

jcoプロジェクトも、typeコマンドを使用してWebAssemblyコンポーネントのJavaScript/TypeScriptバインディングの生成をサポートしています。前述のとおり、VS Codeの特定のニーズを満たすために独自のツールを開発しました。しかし、私たちはjcoチームと隔週でミーティングを行い、可能な限りツール間の整合性を確保しています。基本的な要件は、両方のツールがWITデータ型に対して同じJavaScriptおよびTypeScript表現を使用することです。また、両方のツール間でコードを共有する可能性も探っています。

WebAssemblyコードからTypeScriptを呼び出す

WITファイルは、ホスト（VS Code拡張機能）とWebAssemblyコード間の相互作用を記述し、双方向通信を容易にします。この例では、この機能によりWebAssemblyコードがそのアクティビティのトレースをログに記録できるようになります。これを可能にするため、WITファイルを次のように変更します。

world calculator {

	/// ....

	/// A log function implemented on the host side.
	import log: func(msg: string);

	/// ...
}

Rust側では、これでログ関数を呼び出すことができます。

fn calc(op: Operation) -> u32 {
	log(&format!("Starting calculation: {:?}", op));
	let result = match op {
		// ...
	};
	log(&format!("Finished calculation: {:?}", op));
	result
}

TypeScript側では、拡張機能開発者が必要とする唯一の操作は、ログ関数の実装を提供することです。VS Codeコンポーネントモデルは、必要なバインディングの生成を容易にし、それらはWebAssemblyインスタンスにインポートとして渡されます。

export async function activate(context: vscode.ExtensionContext): Promise<void> {
  // ...

  // The channel for printing the log.
  const log = vscode.window.createOutputChannel('Calculator - Log', { log: true });
  context.subscriptions.push(log);

  // The implementation of the log function that is called from WASM
  const service: calculator.Imports = {
    log: (msg: string) => {
      log.info(msg);
    }
  };

  // Create the bindings to import the log function into the WASM module
  const imports = calculator._.imports.create(service, wasmContext);
  // Instantiate the module
  const instance = await WebAssembly.instantiate(module, imports);

  // ...
}

最初の例と比較すると、WebAssembly.instantiate呼び出しには、2番目の引数としてcalculator._.imports.create(service, wasmContext)の結果が含まれるようになりました。このimports.create呼び出しは、サービスの実装から低レベルのWASMバインディングを生成します。最初の例では、インポートが不要だったため、空のオブジェクトリテラルを渡しました。今回は、デバッガーの下でVS Codeデスクトップ環境で拡張機能を実行します。Connor Peetの素晴らしい仕事のおかげで、Rustコードにブレークポイントを設定し、VS Codeデバッガーを使用してステップ実行できるようになりました。

コンポーネントモデルのリソースの利用

WebAssemblyコンポーネントモデルは、リソースの概念を導入しており、これは状態をカプセル化し管理するための標準化されたメカニズムを提供します。この状態は呼び出し境界の一方側（たとえば、TypeScriptコード）で管理され、もう一方側（たとえば、WebAssemblyコード）からアクセスおよび操作されます。リソースはWASIプレビュー0.2 APIで広く使用されており、ファイル記述子が典型的な例です。この設定では、状態は拡張機能ホストによって管理され、WebAssemblyコードによってアクセスおよび操作されます。

リソースは逆方向にも機能し、その状態はWebAssemblyコードによって管理され、拡張機能コードによってアクセスおよび操作されます。このアプローチは、VS CodeがステートフルサービスをWebAssemblyで実装し、それをTypeScript側からアクセスする場合に特に有益です。以下の例では、Hewlett-Packardの携帯電卓で使われているものと同様の逆ポーランド記法をサポートする電卓を実装するリソースを定義します。

// wit/calculator.wit
package vscode:example;

interface types {

	enum operation {
		add,
		sub,
		mul,
		div
	}

	resource engine {
		constructor();
		push-operand: func(operand: u32);
		push-operation: func(operation: operation);
		execute: func() -> u32;
	}
}
world calculator {
	export types;
}

以下は、Rustで記述された電卓リソースの簡単な実装です。

impl EngineImpl {
	fn new() -> Self {
		EngineImpl {
			left: None,
			right: None,
		}
	}

	fn push_operand(&mut self, operand: u32) {
		if self.left == None {
			self.left = Some(operand);
		} else {
			self.right = Some(operand);
		}
	}

	fn push_operation(&mut self, operation: Operation) {
        let left = self.left.unwrap();
        let right = self.right.unwrap();
        self.left = Some(match operation {
			Operation::Add => left + right,
			Operation::Sub => left - right,
			Operation::Mul => left * right,
			Operation::Div => left / right,
		});
	}

	fn execute(&mut self) -> u32 {
		self.left.unwrap()
	}
}

TypeScriptコードでは、これまでと同じ方法でエクスポートをバインドします。唯一の違いは、バインディングプロセスによって、WebAssemblyコード内のcalculatorリソースをインスタンス化および管理するために使用されるプロキシクラスが提供されるようになったことです。

// Bind the JavaScript Api
const api = calculator._.exports.bind(
  instance.exports as calculator._.Exports,
  wasmContext
);

context.subscriptions.push(
  vscode.commands.registerCommand('vscode-samples.wasm-component-model.run', () => {
    channel.show();
    channel.appendLine('Running calculator example');

    // Create a new calculator engine
    const calculator = new api.types.Engine();

    // Push some operands and operations
    calculator.pushOperand(10);
    calculator.pushOperand(20);
    calculator.pushOperation(Types.Operation.add);
    calculator.pushOperand(2);
    calculator.pushOperation(Types.Operation.mul);

    // Calculate the result
    const result = calculator.execute();
    channel.appendLine(`Result: ${result}`);
  })
);

対応するコマンドを実行すると、出力チャンネルにResult: 60と表示されます。前述のとおり、リソースの状態は呼び出し境界の一方の側に存在し、もう一方の側からハンドルを使用してアクセスされます。リソースと対話するメソッドに渡される引数を除いて、データのコピーは発生しません。

Diagram illustrating how resources are accessed.

この例の全ソースコードは、VS Code拡張機能サンプルリポジトリで入手できます。

RustからVS Code APIを直接使用する

コンポーネントモデルのリソースは、WebAssemblyコンポーネントとホスト間で状態をカプセル化し管理するのに役立ちます。この機能により、リソースを使用してVS Code APIをWebAssemblyコードに標準的に公開できます。このアプローチの利点は、拡張機能全体をWebAssemblyにコンパイルできる言語で作成できるという点にあります。私たちはこのアプローチの探求を開始し、以下にRustで書かれた拡張機能のソースコードを示します。

use std::rc::Rc;

#[export_name = "activate"]
pub fn activate() -> vscode::Disposables {
	let mut disposables: vscode::Disposables = vscode::Disposables::new();

	// Create an output channel.
	let channel: Rc<vscode::OutputChannel> = Rc::new(vscode::window::create_output_channel("Rust Extension", Some("plaintext")));

	// Register a command handler
	let channel_clone = channel.clone();
	disposables.push(vscode::commands::register_command("testbed-component-model-vscode.run", move || {
		channel_clone.append_line("Open documents");

		// Print the URI of all open documents
		for document in vscode::workspace::text_documents() {
			channel.append_line(&format!("Document: {}", document.uri()));
		}
	}));
	return disposables;
}

#[export_name = "deactivate"]
pub fn deactivate() {
}

このコードがTypeScriptで書かれた拡張機能と似ていることに注目してください。

この探求は有望に見えますが、現在のところこれ以上進めないことにしました。主な理由は、WASMでの非同期サポートの欠如です。VS Code APIの多くは非同期であり、WebAssemblyコードに直接プロキシするのが困難です。WebAssemblyコードを別のワーカーで実行し、WebAssemblyワーカーと拡張機能ホストワーカー間のWASI Preview 1サポートで使用されているのと同じ同期メカニズムを採用することも可能です。しかし、このアプローチは同期API呼び出し中に予期せぬ動作を引き起こす可能性があります。なぜなら、これらの呼び出しは実際には非同期で実行されるためです。結果として、2つの同期呼び出しの間で観測可能な状態が変化する可能性があります（たとえば、setX(5); getX();が5を返さない可能性があります）。

さらに、0.3プレビュー期間中にWASIに完全な非同期サポートを導入するための取り組みが進行中です。Luke Wagner氏は、WASM I/O 2024で非同期サポートの現状について最新情報を提供しました。より完全でクリーンな実装を可能にするため、このサポートを待つことにしました。

対応するWITファイル、Rustコード、およびTypeScriptコードに興味がある場合は、vscode-wasmリポジトリのrust-apiフォルダーにあります。

次に来るもの

現在、WebAssemblyコードが拡張機能開発で活用できるさらなる領域を網羅する続編のブログ記事を準備中です。主なトピックは以下の通りです。

  • WebAssemblyで言語サーバーを記述する。
  • 生成されたメタモデルを使用して、長時間実行されるWebAssemblyコードを透過的に別のワーカーにオフロードする。

コンポーネントモデルのVS Code慣用的な実装が整ったことで、VS Code向けWASI 0.2プレビューの実装への取り組みを継続しています。

よろしくお願いいたします。

DirkとVS Codeチーム

ハッピーコーディング！