ChatGPTClaudeGrok / X / CursorGemini

DSH plugin file completion: abort and stale results

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessfile referenceAbortSignalrace condition
A list that flashes old results is usually a cancellation bug. Where the signal travels, why cancel is not failure, three races, and a minimal implementation.

When the completion list flashes old results, it is almost always "the new request is out, the old one is still in flight": DSH plugin's list(agent, query, signal) provides the cancellation hook, but you must also discard stale responses afterward. Debouncing alone reduces the frequency; it does not remove the race.

Why DSH plugin lists flash while typing

Because discovery fires per keystroke while responses have no ordering guarantee. (source) A reproducible sequence:

text
t1  type "s"       -> request A
t2  type "sr"      -> request B
t3  B returns      -> render ["src/"]
t4  A returns      -> render ["scripts/"]   <- flash

The user sees "I typed sr but the list jumped back to scripts". Nothing threw an exception; A simply arrived after B.

The signature of this bug is that it appears only when network or disk is slow. A fast local machine hides it, so manual testing cannot confirm the fix — you must inject delay.

DeepSeek Harness: Where the signal travels

In the interface parameters, from the host down to the provider. (source) Both entry points accept signal:

  1. ctx.fileReferences.list(agent, query, signal) — the abstraction seam;
  2. ctx.sessionFileReferences.list(agent, query, signal) — the remote adapter.

The adapter must not swallow the signal, and providers must not ignore it. The official wording is "caller cancellation": the caller no longer needs this result, so the provider may stop.

It covers one call, not a global switch. Every input event gets its own call and its own signal.

DeepSeek Harness: Cancel is not failure

Cancellation is expected; failure is exceptional. They must not share one UI path. (source) Comparison:

CaseMeaningHost reaction
Signal firesCaller no longer needs itDiscard silently, no prompt
Provider throwsDiscovery failedMay notify, keep the previous list
Empty arrayNo candidatesShow an empty state

Treat cancellation as failure and every fast keystroke flashes an error. Treat failure as cancellation and real permission or path problems disappear silently.

A simple rule follows: only non-cancellation exceptions should surface an error.

Three races in DSH plugin completion

Classify by where they happen; each has a different fix. (source) Comparison:

RaceScenarioHandling
Request levelAn old request returns after a new oneCancel the old request and drop by sequence number
Render levelState updates after the next inputCompare against the current query before rendering
Lifecycle levelA response arrives after unmountCancel on unmount and discard the response

The third is the most overlooked: the user navigates away, the callback still runs, and at best it renders nothing useful; at worst it touches destroyed state.

All three share one solution: make each result carry the input it belongs to, instead of relying on "last to return wins".

DeepSeek Harness: A minimal host implementation

Four actions cover the vast majority of cases. (source) Steps:

  1. Increment a sequence number on every input and create a new AbortController;
  2. Abort the previous controller before issuing the request;
  3. When a response arrives, compare its sequence with the current one and drop it if they differ;
  4. On unmount, abort the current controller and clear the sequence.

The shape looks like this:

ts
let seq = 0
let controller: AbortController | undefined

async function onInput(query: string) {
  controller?.abort()
  controller = new AbortController()
  const current = ++seq
  const items = await list(agent, query, controller.signal)
  if (current !== seq) return
  render(items)
}

There is no debounce and no retry here. It guarantees one thing: the screen always reflects the most recent input.

DeepSeek Harness: Verifying cancellation

Construct the race with artificial delay instead of typing fast. Steps:

  1. Make the test provider delay s by 300 ms and answer sr immediately;
  2. Type s then sr and confirm only the sr result is displayed;
  3. Unmount the component right after typing and confirm no render warning;
  4. Make the provider throw and confirm the error shows while the previous list stays.

Step 2 is the core assertion: the final state must be decided by the last input, not by the last response.

Step 3 checks lifecycle cancellation; step 4 checks that cancellation and failure were not conflated.

That completes the completion chain. To revisit why candidates carry only paths, read DSH plugin file reference candidates; to parse input correctly, read how the file reference query works; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, file-reference/src/index.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why does the DSH plugin completion list flash old results while typing fast?

Usually not a provider bug, but a DSH plugin request-ordering issue. DSH plugin discovery fires at keystroke rate, so an earlier request can return after a later one and overwrite it. The host must cancel the previous request and discard stale responses.

After a DSH plugin signal fires, should a provider throw or return an empty list?

Cancellation is not a business failure in DSH plugin. DSH plugin defines the signal as the caller's cancellation boundary, so the provider stops working; the host should neither render an error nor treat it as no candidates.

With DSH plugin, is file reference cancellation the same as session reference cancellation?

No, they act at different stages in DSH plugin. File reference cancellation happens during discovery and stops candidate requests; session reference cancellation happens in prepare and blocks context publication. They share the signal shape but differ in meaning.

Can debouncing replace cancellation in DSH plugin completion?

No, debouncing cannot replace cancellation in DSH plugin. Debouncing only reduces request count, and DSH plugin can still return old results at latency boundaries. Cancellation invalidates stale requests; the two solve different problems.

Related Terms

AbortSignal
An AbortSignal is the cancellation signal passed by the caller; a provider should stop discovery and abandon its result when it fires.— DeepSeek Harness reference - Session references
keystroke rate
Keystroke rate describes discovery triggered at typing frequency, which means dense requests with very short lifetimes.— DeepSeek Harness reference - Session references
stale result
A stale result is a response for an older query that arrives after the user typed more; rendering it overwrites newer candidates.— DeepSeek Harness reference - Session references
race
A race is a mismatch between the completion order and the initiation order of async requests, making the final display depend on who returns last.— DeepSeek Harness reference - Session references

Sources