ChatGPTClaudeGrok / X / CursorGemini

DSH plugin async boundaries: why apply must stay synchronous

Plugin DevelopmentPublished 2026-11-17Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessPlugin developmentAsync setupctx.effect
Async setup in apply looks fine until it races the first request. Covers the sync entry, effect setup, unhandled rejections, and unload mid-flight.

The most invisible bug in plugin development is an async apply that nobody awaits. The framework calls apply synchronously during LOADING and treats the return as done; whatever you awaited runs after the plugin is already usable. Most async problems in DSH plugin land on that timeline.

DSH plugin apply is a synchronous entry

The framework does not queue behind your Promise. (source)

The documented state machine puts apply inside LOADING: dependencies arrive, apply runs, a normal return moves to ACTIVE, a throw moves to FAILED. There is no "await the Promise" state, so an async apply does not slow loading down; it just moves the async part outside the loading window.

Three consequences follow. First, the plugin is already marked usable while its internal state may be empty. Second, an error thrown in the async section never becomes FAILED, so the plugin looks healthy. Third, on hot reload the old instance is unloaded while last round's task is still running, and the new round starts another one.

The quickest diagnosis is the return type. If apply returns a Promise, you have turned a synchronous entry into an async container.

Where async setup belongs in a DSH plugin

Setup and cleanup must be registered as a pair, and ctx.effect is that pair. (source)

  1. Register the effect synchronously in apply — apply does not await; it only attaches the work to the Fiber.
  2. Start the async work inside the callback — read config, open connections, build an index.
  3. Return a disposer — cancel unfinished work, close what opened, clear timers.
  4. Keep readiness in the closure — a Promise or a ready flag for later use sites.

The gain is not tidier code but an owned teardown path: unload always calls the disposer, and you can cancel there. Conversely, an await written directly in apply has no hook that will touch it on unload.

ts
export function apply(ctx: Context) {
  let cancelled = false
  const ready = (async () => {
    const config = await loadConfig()
    if (cancelled) throw new Error('cancelled')
    return config
  })()

  ctx.effect(() => {
    return async () => {
      cancelled = true
      await ready.catch(() => {})
    }
  })
}

ready is created once and shared; cancelled lets the task exit after unload instead of finishing and writing a stale cache.

Where DSH plugin unhandled rejections go

They do not become FAILED, do not stop the plugin, and often vanish into the console. (source)

FAILED means "apply threw". A failure in the async section happens in another microtask, long after loading reported success, so no state change and no reload follow.

The symptom is familiar: a log line says initialization failed, the UI looks fine, and then some request returns empty data. When debugging, do not trust the Fiber state alone; check whether the async section catches its own failures and reports them somewhere observable.

A workable pattern wraps the async setup, records the reason, and rejects the shared ready Promise so use sites receive an explicit error. A loud failure is easier to fix than a silent retry.

The DSH plugin race with the first request

Nothing pauses requests until your initialization finishes. (source)

Once the plugin is ACTIVE it can be called, while async setup may still be in flight. Two orderings appear in practice: setup finishes first and everything works, or a request arrives first and reads an empty cache.

Three ways to handle it, from cheapest to most polished:

  1. Share one ready Promise — use sites await it, so only the first request is slower.
  2. Return an explicit error when not ready — never an empty array or undefined, so callers can distinguish "not yet" from "nothing".
  3. Write a placeholder, fill it later — return a usable empty shape and refresh through an event or status field.

The first is the safest, the third has the best perceived latency. Whichever you pick, never restart initialization per request; that turns a race into a stampede.

DSH plugin unload while async work is in flight

Unload guarantees the disposer runs, not that your task stops by itself. (source)

The documented dispose promise has three parts: remove all registrations, recursively unload children, and resolve after async cleanup settles. Note that "async cleanup" means disposers that return Promises, not arbitrary work you forgot to register.

So the disposer needs two jobs: mark the work cancelled and wait for it to exit. A common mistake closes the connection but leaves an in-flight read running, and logs keep printing after unload.

Also remember that disposers run in reverse order but concurrently. If "stop polling before closing the connection" matters, both steps belong in one disposer that awaits them in sequence rather than in two separate effects.

Verification: three comparisons

Change one variable at a time to separate the sync entry from the async section. (source)

  1. Write an async apply that waits two seconds before registering a capability, then call it immediately after boot; assert the call fails or returns empty, proving the framework did not wait.
  2. Switch to a synchronous apply plus async setup inside ctx.effect, have use sites await the shared ready Promise, and assert the first call is slower but correct.
  3. Trigger unload halfway through setup and assert the disposer ran, the task saw the cancel flag, and logging stopped.
  4. Save a file with HMR on and assert the old instance's task is not running in parallel with the new one.

If step 3 keeps logging, you closed resources but never cancelled the task. If step 4 shows two streams of output, the task lives in a module-level variable instead of an effect-owned closure.

Startup cost and async boundaries are two sides of one decision: moving work out speeds boot but moves the race to runtime, which is why startup cost is the natural next read; teardown ordering is covered in cleanup order and reverse disposers.

One line to close: apply only registers, async setup belongs in ctx.effect with a cancel path, the first request shares one ready Promise, unload stops work before closing resources, and HMR must leave no old task behind.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What happens if I make DSH plugin apply async?

No: DSH plugin apply is synchronous and the framework does not await it. apply is called during LOADING and the plugin becomes ACTIVE as soon as it returns, so an async apply leaves a floating Promise running after activation, with failures nobody receives.

Should async setup go in DSH plugin ctx.effect, not apply?

Yes: DSH plugin async setup belongs in ctx.effect because cleanup needs an owner. ctx.effect registers the disposer on the Fiber, so unload can cancel the task and close what it opened; setup written directly in apply has no registration and keeps running after unload.

What if the first request beats DSH plugin async setup?

DSH plugin does not pause for you, so let the use site await the same readiness Promise. Share one Promise in the closure, and return an explicit error when not ready rather than an empty result, so callers can tell missing data from unfinished work.

Who guarantees DSH plugin cleanup order when unload races?

Cleanup order is owned by the DSH plugin effect disposer. Disposers run in reverse order but async ones run concurrently, so steps that must happen in sequence belong in one disposer that awaits them; dispose resolves after all async cleanup settles.

Related Terms

apply
apply is the synchronous entry of a DSH plugin, called during LOADING after injected services are ready, where you register capabilities or resources.— DeepSeek Harness reference - Your first plugin
ctx.effect
ctx.effect is the registration API for a custom resource; the disposer it accepts, which the framework calls on unload to close connections or cancel async work.— DeepSeek Harness reference - Plugins and lifecycle
LOADING
LOADING is the Fiber state meaning dependencies are ready and the framework is executing apply; a throw moves it to FAILED, a normal return to ACTIVE.— DeepSeek Harness reference - Plugins and lifecycle
dispose
dispose is the operation that terminates a plugin instance, removing its registrations, recursively unloading children, and resolving after all async cleanup completes.— DeepSeek Harness reference - Plugins and lifecycle

Sources