Skip to content

fix(core): refresh plugins in background - #45993

Merged
kitlangton merged 6 commits into
v2from
plugin-startup
Aug 28, 2026
Merged

kitlangton merged 6 commits into
v2from
plugin-startup

Conversation

@kitlangton

@kitlangton kitlangton commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

Why

A fresh server can spend several seconds checking the network before it imports an already-cached plugin. Mutable package refresh runs during repository-marker discovery, so registry or Git latency blocks the initial Location graph and prompt even when a usable installation is available.

What Changes

Plugin source Startup behavior
Cached mutable npm or Git spec Import immediately, then refresh once in the background
Uncached package Install before first import as before
Exact npm version or full Git commit Reuse the pinned installation without refreshing
Failed background refresh Keep the cached plugin active

Automatic updates remain enabled. The already-imported plugin definition stays active in the current process; the next server process imports the refreshed package.

Refresh Boundary

sequenceDiagram
    participant Startup as Location startup
    participant Supervisor as Plugin supervisor
    participant Loader as PluginModule
    participant Cache as Package cache
    participant Refresh as Background refresh

    Startup->>Supervisor: load configured plugins
    Supervisor->>Loader: load configured plugin
    Loader->>Cache: resolve cached package
    Cache-->>Loader: cached entrypoint
    Loader->>Loader: import and decode plugin
    Loader-->>Supervisor: plugin definition
    Supervisor->>Supervisor: activate all plugins
    Supervisor-)Refresh: start detached refresh
    Supervisor-->>Startup: open readiness
    Refresh->>Cache: update cached package
    Note over Startup,Cache: Next server process imports the update
Loading

Repository-marker discovery stays cache-only. The supervisor starts the detached refresh only after all plugin setup has completed, so imports, activation, and readiness do not wait for Arborist or the network.

The regression test blocks plugin setup and verifies that no refresh starts, then blocks the refresh itself and verifies that supervisor flush still completes. It releases both barriers before teardown so no detached test work remains.

Scope

This changes refresh scheduling and treats a successful first install as the service's refresh attempt. It adds no command, configuration, protocol, generated-client surface, or package-cache format.

Verification

# packages/core
bun run test test/npm.test.ts test/plugin/module.test.ts test/config/plugin.test.ts test/project.test.ts
bun run test
bun typecheck
bun run build

# packages/cli
bun run test test/plugin-add.test.ts
bun typecheck

# packages/www
bun typecheck
bun run check:generated
bun run build

# repository pre-push hook
bun turbo typecheck --concurrency=3

The focused Core run passed 55 tests with one existing skip. The complete Core suite passed 3,794 tests with 40 skips and no failures. CLI tests, affected package builds/checks, the documentation build, and all 33 pre-push typecheck tasks passed.

A matched standalone benchmark used the same rebased source and warm package cache, toggling only whether the first package refresh was synchronous or detached:

Measurement Synchronous refresh Background refresh
Prompt visible 13.89 s 5.14 s
Initial Location graph 9.730 s 0.941 s

@kitlangton kitlangton changed the title fix(core): avoid refreshing plugins during startup fix(core): refresh plugins in background Aug 28, 2026
@kitlangton
kitlangton enabled auto-merge (squash) August 28, 2026 19:37
@kitlangton
kitlangton merged commit aea3e7c into v2 Aug 28, 2026
14 checks passed
@kitlangton
kitlangton deleted the plugin-startup branch August 28, 2026 19:43
jinhuang712 pushed a commit to jinhuang712/opencode that referenced this pull request Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant