Use synchronous hooks for ESM ASAR resolution

[Dmitriy Vasyura (dmitrivMS)]

Background

VS Code installs a custom ESM resolution hook in Electron processes to:

1. Map ESM fs imports to Electron's ASAR-unaware original-fs.
2. Resolve application bare package imports from node_modules.asar.
3. Prefer dependencies bundled closer to an importer.
4. Prevent resolution from escaping the application into an outer checkout's node_modules.

The hook currently uses Node's asynchronous module.register. Node runs those hooks on a dedicated loader worker, while static module linking synchronously waits for the worker.

This became visible while investigating Windows startup performance after Agent Host began prewarming during WorkbenchPhase.BlockRestore. An Agent Host utility-process profile attributed:

• 149 ms to node:internal/modules/esm/hooks#makeSyncRequest
• 92 ms to ESM source compilation
• 64 ms to process spawn

Most makeSyncRequest time was the main Agent Host thread waiting synchronously for the loader worker during static module linking.

Node 24 provides module.registerHooks, which runs synchronous hooks in-process. VS Code already uses this API in the extension host.

Change

Port the existing ASAR resolver to module.registerHooks.

Resolution behavior remains the same:

• ESM fs maps to node:original-fs.
• Bare packages first use default resolution so an importer's closer bundled dependency wins.
• A default resolution outside the application tree is rejected.
• Missing packages are looked up in node_modules.asar.
• Package self-reference resolution still applies real exports, main, and ESM import conditions.
• Packages without exports retain the direct, escape-proof archive fallback.
• Electron built-ins remain excluded.
• Resolution tracing through VSCODE_ASAR_TRACE remains available.

Synchronous hooks also apply to CommonJS resolution, unlike asynchronous hooks. The resolver therefore explicitly bypasses contexts containing the require condition, preserving existing require() and createRequire() behavior.

Startup scenario improvement

The final A/B uses two fully bundled current-source Windows desktop applications:

• Same source revision
• Same official Electron runtime
• Same product/resources/extensions
• Same minification and NLS processing
• Complete out/ directories differ only by this change

Each app received three warmups followed by 30 measured starts. Every individual start was interleaved, alternating A/B and B/A order. The standard performance scenario opens a deterministic local folder and one text file with extensions, updates, experiments, workspace trust, GPU, telemetry, and crash reporting disabled.

Metric	Baseline	Synchronous hook	Paired change
Total startup	1435.5 ms	1420.5 ms	-18.5 ms
Bootstrap 95% interval			-33.5 ms to -7.0 ms
Main bundle load	152.0 ms	118.0 ms	-33.5 ms
Workspace service init	54.0 ms	43.5 ms	-11.0 ms
Storage init	22.0 ms	18.0 ms	-4.0 ms

The phase measurements overlap and should not be summed. The conservative end-to-end startup win is 18.5 ms on this Windows host.

Improvements to other scenarios

The same bootstrap is shared by Electron main/CLI and bootstrap-fork processes such as Agent Host, extension host, shared/process services, file watchers, and terminal hosts.

Measured improvements in the packaged A/B:

Scenario	Baseline	Synchronous hook	Paired change
Agent Host start to protocol connect	962.5 ms	759.0 ms	-203.0 ms
Shared-process connection	518.0 ms	420.5 ms	-98.0 ms
Extension registration	761.5 ms	734.5 ms	-20.0 ms

Agent Host launch timing relative to workbench startup is unchanged (+4 ms, interval includes zero), while protocol connection becomes substantially faster. This preserves the early prewarm behavior required by #324330 rather than moving work after startup.

The packaged CLI also starts successfully through the synchronous hook.

Compatibility / lack of regressions

Validation covered the behavioral differences between asynchronous and synchronous Node hooks:

• Direct packaged assertion:
  • ESM import('fs') resolves to original-fs.
  • CommonJS require('fs') remains the normal Electron/Node module.
• Packaged GUI standard startup succeeds.
• Packaged CLI --version succeeds.
• Packaged Agent Host resolves ASAR dependencies, connects, and lists sessions.
• No module resolution errors in correctly bundled baseline/fix runs.
• Agent Host launch is not deferred.
• Production desktop bundling succeeds.
• Client typecheck succeeds.

Tests:

AgentHostPrewarmContribution and LocalAgentHostService: 19 passing
Agent Host diff worker: 6 passing

The diff-worker coverage is relevant because synchronous hooks are process-local and are not inherited by worker threads; the existing worker imports only built-ins/internal files and continues to pass.

Two independent implementation/diff reviews found no significant correctness or compatibility issue.

Commands

npm run typecheck-client
node build\next\index.ts bundle --minify --nls --target desktop --out perf-test\cache\bundle-sync-hook-pr
scripts\test.bat --run src\vs\workbench\services\agentHost\test\electron-browser\agentHostService.test.ts --run src\vs\platform\agentHost\test\electron-browser\localAgentHostService.test.ts --run src\vs\platform\agentHost\test\node\diffWorkerMain.test.ts

[Copilot]

Pull request overview

Migrates Electron ASAR resolution to synchronous Node.js hooks, reducing startup overhead while preserving existing resolution behavior.

Changes:

• Replaces module.register with synchronous module.registerHooks.
• Preserves ASAR fallback, package self-reference, tracing, and original-fs mapping.
• Bypasses CommonJS resolution to retain existing require() behavior.

Show a summary per file

File	Description
src/bootstrap-esm.ts	Implements synchronous, in-process ASAR resolution hooks.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Balanced

[Mohammad javad Dianat (dianatofficial)]

Great catch on this edge case. Fallback logic is robust.