DSH plugin file completion: abort and stale results
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:
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:
ctx.fileReferences.list(agent, query, signal)— the abstraction seam;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:
| Case | Meaning | Host reaction |
|---|---|---|
| Signal fires | Caller no longer needs it | Discard silently, no prompt |
| Provider throws | Discovery failed | May notify, keep the previous list |
| Empty array | No candidates | Show 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:
| Race | Scenario | Handling |
|---|---|---|
| Request level | An old request returns after a new one | Cancel the old request and drop by sequence number |
| Render level | State updates after the next input | Compare against the current query before rendering |
| Lifecycle level | A response arrives after unmount | Cancel 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:
- Increment a sequence number on every input and create a new
AbortController; - Abort the previous controller before issuing the request;
- When a response arrives, compare its sequence with the current one and drop it if they differ;
- On unmount, abort the current controller and clear the sequence.
The shape looks like this:
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:
- Make the test provider delay
sby 300 ms and answersrimmediately; - Type
sthensrand confirm only thesrresult is displayed; - Unmount the component right after typing and confirm no render warning;
- 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
FAQ
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.
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.
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.
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
- DeepSeek Harness reference - Session references· deepseek-ai
- file-reference/src/index.ts· deepseek-ai