Investigate bootstrap-time runtime import failures in plugin initialization

[NaNomicon]

Summary

The plugin can fail during startup because some transitive dependencies are imported too early during plugin bootstrap.

This issue tracks investigation and potential fixes for bootstrap-time runtime failures caused by eager top-level imports in the plugin dependency graph.

Current observed failures

We have seen bootstrap-time failures such as:

1. Transformers / sharp path

   Missing 'default' export in module '.../node_modules/sharp/lib/index.js'

2. OpenCode provider / OIDC path

   Export named 'getVercelOidcToken' not found in module '.../@vercel/oidc/dist/index.js'

What we know so far

• The failure happens during plugin bootstrap, before the affected features are actually used.
• Top-level imports can pull in runtime-sensitive dependencies too early.
• This appears to affect transitive dependency graphs, not just the immediate plugin entrypoint code.
• The sharp-related failure has also been reproduced in a clean OpenCode environment, so it does not appear to be only host-specific setup noise.

Likely problematic bootstrap edges

1. Embedding stack

src/services/embedding.ts imports @xenova/transformers at module top level.

That means the plugin may reach the sharp dependency graph during startup even when local embeddings are not needed for the active config or code path.

2. OpenCode provider stack

src/index.ts imports ./services/ai/opencode-provider.js at module top level.

That can pull in the AI/provider/OIDC stack during startup even when provider-backed features are not needed immediately.

Candidate directions to test later

These are hypotheses to verify, not confirmed fixes:

1. Lazy-load transformers

   • defer @xenova/transformers until local embeddings are actually needed
   • goal: avoid reaching sharp during plugin bootstrap

2. Lazy-load OpenCode provider stack

   • defer ./services/ai/opencode-provider.js until provider-backed logic is actually needed
   • goal: avoid reaching OIDC-related dependencies during plugin bootstrap

Important caution

These changes may only defer failures rather than fully fix them.

A successful bootstrap is useful, but we still need to verify that the deferred code paths work correctly once exercised.

Repro notes

Example repro command:

opencode debug config --print-logs

Suggested next steps

1. Build minimal repros for each bootstrap edge

   • transformers/sharp
   • opencode-provider/oidc

2. Test lazy-loading one dependency edge at a time

3. Verify two things separately:

   • plugin startup succeeds
   • deferred runtime path still works when actually invoked

4. Compare behavior across:

   • plain Bun
   • clean OpenCode environment
   • local OpenCode install

5. Decide whether the long-term fix belongs in:

   • plugin bootstrap structure
   • dependency strategy
   • upstream runtime issue tracking
   • or a combination of the above

Status

Tracking issue only.
Implementation and validation will happen in a later pass.

[NaNomicon]

Additional repro note:

I also captured a minimal bare-OpenCode Docker repro as a secret gist:
https://gist.github.com/NaNomicon/9d1951addc4dc2c14d3c4014580b4495

It contains:

• Dockerfile
• opencode-mem.js file-based plugin shim
• README.md with build/run commands

The purpose is to reproduce plugin bootstrap/runtime failures in a clean OpenCode environment without depending on a host-specific local setup.

[NaNomicon]

I dug into this more deeply and the findings point to two separate bootstrap-sensitive import chains, both of which are currently being triggered too early during plugin startup.

Confirmed problematic bootstrap edges

1. Embedding stack: @xenova/transformers → sharp

This is the main cause of the sharp-related startup failure.

Current eager path:

• src/index.ts → ./services/client.js
• src/services/client.ts → ./embedding.js
• src/services/embedding.ts → top-level import { pipeline, env } from "@xenova/transformers"

There is also a duplicate eager path through the web server:

• src/index.ts → ./services/web-server.js
• src/services/web-server.ts → ./api-handlers.js
• src/services/api-handlers.ts → ./embedding.js

Additional parse-time side effects in embedding.ts make this worse:

• env.allowLocalModels = true
• env.allowRemoteModels = true
• env.cacheDir = ...
• export const embeddingService = EmbeddingService.getInstance()

So even if embeddings are never used during startup, the plugin still reaches the transformers/sharp dependency graph during module evaluation.

External context: this aligns with known Bun/sharp interop and native-loading fragility:

• Bun module resolution docs: CommonJS gets a synthetic default export only after successful evaluation, which means failures in the load chain can surface as confusing missing-export errors rather than the original native-load failure: https://bun.sh/docs/runtime/module-resolution
• Error when using sharp module with Bun — oven-sh/bun#5345: Error when using sharp module with Bun oven-sh/bun#5345
• MissingSharp: Could not find Sharp — oven-sh/bun#9618: MissingSharp: Could not find Sharp. oven-sh/bun#9618
• sharp 33-34 isn't working — oven-sh/bun#21610: sharp 33-34 isn't working oven-sh/bun#21610
• transformers.js not working with Bun — huggingface/transformers.js#558: Not working with Bun huggingface/transformers.js#558

My read is that lazy loading is the correct mitigation here, even if it does not “fix Bun + sharp” globally.

---

2. Provider stack: opencode-provider → AI SDK / OIDC

This is the likely cause of the getVercelOidcToken export failure.

Current eager path:

• src/index.ts → top-level import of ./services/ai/opencode-provider.js
• src/services/ai/opencode-provider.ts → top-level imports of:
  • ai
  • @ai-sdk/anthropic
  • @ai-sdk/openai

The external evidence here is especially strong:

• Matching OpenCode regression report:
  • Windows + OpenCode Desktop v1.3.13: plugin fails to load with getVercelOidcToken export error — anomalyco/opencode#20663: Windows + OpenCode Desktop v1.3.13: plugin fails to load with getVercelOidcToken export error anomalyco/opencode#20663
• Bun named-export interop bug for getter-based CommonJS exports:
  • Can't import from Object.defineProperty(exports, ...) — oven-sh/bun#10334: Can't import from Object.defineProperty(exports, ...) oven-sh/bun#10334
• Related Bun named-export resolution problems:
  • Monorepo in windows: Export named ... not found in module — oven-sh/bun#10988: Monorepo in windows get error: Export named 'shared' not found in module oven-sh/bun#10988
  • Could not resolve named exports for package mixed with esm and cjs exports — oven-sh/bun#24341: Could not resolve named exports for package mixed with esm and cjs exports oven-sh/bun#24341
• @vercel/oidc added browser conditional exports in:
  • feat(oidc): add conditional export for browsers — vercel/vercel#14005: feat(oidc): add conditional export for browsers vercel/vercel#14005

The likely underlying issue is Bun/OpenCode runtime behavior around resolving @vercel/oidc through this dependency chain, especially on Windows. Regardless of the exact upstream root cause, eagerly importing this provider stack at bootstrap is what makes the plugin fail before the feature is even used.

---

Additional bootstrap risks found

While tracing the graph, I found a few other parse-time risks worth noting:

• src/config.ts
  • creates directories with mkdirSync(...) at module parse time
• src/services/user-profile/user-profile-manager.ts
  • singleton export opens SQLite at module parse time
• src/services/user-prompt/user-prompt-manager.ts
  • same pattern, plus DDL/DML at module parse time
• src/services/language-detector.ts
  • eagerly imports franc-min and iso-639-3

These are not the primary crashers reported in this issue, but they do add avoidable bootstrap work and fragility.

---

Recommended fix direction

The codebase already has the right pattern elsewhere: config-gated / handler-local await import(...) for expensive or optional dependencies.

The minimum fix for this issue looks like:

1. Lazy-load opencode-provider in src/index.ts

   • remove the top-level static import
   • import it only inside the async path that actually needs it

2. Defer @xenova/transformers in src/services/embedding.ts

   • move the import into first-use initialization (for example inside initializeModel())
   • also defer the env setup so it does not run at module parse time

3. Re-check the duplicate eager embedding path

   • especially client.ts and api-handlers.ts
   • make sure they do not reintroduce early module evaluation of the embedding stack

This matches lazy-loading patterns the repo already uses successfully in:

• src/plugin.ts
• src/services/auto-capture.ts
• src/services/user-memory-learning.ts
• parts of src/index.ts and src/services/api-handlers.ts

---

Important caution

This likely solves bootstrap failure, but it may only defer runtime failure if the underlying environment still cannot load sharp or the OIDC chain when actually used.

So verification should explicitly check two things separately:

1. plugin startup succeeds
2. deferred runtime paths still work when invoked

That feels like the right boundary for this issue: make plugin bootstrap resilient to fragile optional dependencies, even if some underlying runtime/provider issues still need separate upstream tracking.