dsh-cf-handoff
DSH web_fetch 的 Cloudflare 人工接管层：当抓取遇到 Cloudflare 中间页面时，在用户自己的浏览器中打开 URL，暂停代理，并根据人工回复继续执行。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:wtwgo114514/dsh-cf-handoff#34a4e0c2b32c778d5b6ed6f77cb09a695fee50bfCf Handoff 以 dsh-cf-handoff 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
🇨🇳 中文说明在这里 — README.zh-CN.md（讲清它干什么、怎么装、怎么用， 不要求读完全文）
A Cloudflare human-handoff layer for DeepSeek Harness web_fetch.
When a fetch hits a Cloudflare interstitial, the agent cannot get through by retrying — a human has to open the URL once in a real browser. This plugin detects the interstitial, opens the URL in the user's own default browser, pauses the agent on a question in the DSH Web GUI, and resumes the same fetch call from the human's answer.
Non-goal, stated up front: this plugin never tries to solve a challenge. It contains no solver, no CAPTCHA service, no browser automation, and no cookie theft. It detects, it hands off, it resumes. The human is the mechanism.
最近核对：2026-10-17（DSH 0.1.5-rc.2）。检测特征来自对真实站点的实测
响应，不是从文档推测的；见下文 "Verified against real responses"。
Cloudflare 的特征会变，所以这一行是这份文档里最需要定期更新的一行。
The design brief for this plugin was written from 推测的 API and marked six
assumptions 待核实. All six were checked against the installed source. Four
were wrong, and two of those four were wrong in a way that invalidated the
intended design — the plugin could not have been built as written.
| # | Assumption in the brief | Verdict | What the source actually provides |
|---|---|---|---|
| 1 | agent/pre-step exists and can intercept tool results | ⚠️ exists, wrong role | It is a step-admission waterfall, not a tool-result node. See below. |
| 2 | Signature (session, step, next), step carries toolCalls/toolResults | ❌ wrong | (payload: { agent, messages, turn, step, signal }, next). No tool results anywhere in it. |
| 3 | next() supports { kind: 'skip' | 'reject' | 'replace' } | ❌ wrong | PreStepDecision is { kind: 'reject' } | { kind: 'enter', messages }. Input rewriting is deliberately excluded. |
| 4 | ctx.userQuestions.ask(session, {...}) | ✅ exists, different call shape | ask(request) — a single object. The signature was wrong, the seam is real and is the correct one. |
| 5 | ctx.browser exposes navigate/read/isHeadless/setHeadless/currentUrl | ❌ does not exist | There is no browser capability in DSH at all. ctx.web is request/response HTTP only. |
| 6 | browser tools are named browser_* | ❌ does not exist | The only web tools are web_search and web_fetch. |
DSH ships no browser control layer: no Playwright, no Puppeteer, no CDP, no
WebDriver dependency, and no browser_* tool registration. The brief's
"if headless, switch to a visible window and re-navigate" step is therefore
physically unimplementable — there is no window to switch, and
dsh-web-fetch-http keeps no cookie jar or session, so a challenge cleared in
some other browser would not be reused by the provider anyway.
ctx.web is the whole network capability:
// @deepseek-ai/dsh-web/lib/types/index.d.ts
fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
WebFetchResult is { url, statusCode, body, truncated }. There is no
headers field, so cf-mitigated, server: cloudflare, and cf-ray — the
canonical header signals — are not observable at this layer. That single fact
dictates the whole detection design: detection must work from the status code
and the decoded body alone.
agent/pre-stepagent/pre-step is dispatched with Scoped<Agent> and a payload of
{ agent, messages, turn, step, signal }, and its decision type is:
// @deepseek-ai/dsh-agent/lib/types/runtime-types.d.ts
export type PreStepDecision = { kind: 'reject' } | {
kind: 'enter';
messages: UserMessage[];
startsRequestSeries?: true;
};
It decides which messages enter a step. It never sees a tool result. The
brief's assumption 3 (skip/reject/replace over tool results) does not exist
in any form there.
The real tool-result seam is in dsh-tools:
'tools/pre-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>;
'tools/post-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>;
with
export type PreToolDecision =
| { kind: 'allow' }
| { kind: 'deny'; reason: string }
| { kind: 'ask'; reason?: string };
export type PostToolDecision =
| { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }
| { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }
| { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] };
The PreToolDecision doc comment explains why rewriting is missing:
"Input rewriting is excluded because arguments are already logged and presented."
ctx.web.fetch instead of using tools/post-executetools/post-execute can replace a finished result — including the one
projection the model sees — but it cannot make the tool run again. The
brief's recovery requirement is "resume from the breakpoint, don't re-run the
probe", and for a blocked page the only way to obtain content is to fetch again
after the human acted. A post-execute listener would have to re-issue the fetch
itself and could only ever fake resumption.
Wrapping ctx.web.fetch puts the pause-and-retry inside the original call:
web_fetch awaits ctx.web.fetch(...), that await is suspended while the human
answers, and the same call returns the real post-verification content. No second
tool invocation, no fabricated result. That is what makes this a resumption
rather than a retry loop.
The obvious-looking approach — register a WebFetchProvider — is a trap.
dsh-web's resolver (dsh-web/lib/index.js) fails with
WEB_PROVIDER_AMBIGUOUS when fetchProvider is unconfigured and more than one
provider is available, and registerProvider throws
WEB_DUPLICATE_PROVIDER for a repeated id. Adding a provider would therefore
change provider selection for every unrelated fetch in the process, and the
change would outlive the plugin's usefulness. Decorating the service method is
disposable and leaves the registry untouched.
ctx.userQuestions.ask() is a scope-filtered waterfall. From
dsh-user-questions/lib/index.js:
return await (agent === void 0
? this.ctx.waterfall("user-questions/request", request, noAnswerer)
: this.ctx.waterfall(scopeTarget(agent, agent), "user-questions/request", { ...request, agent }, noAnswerer));
The Web GUI answerer is composed on the Agent-scoped waterfall, and
user-questions/request is a mode: waterfall remote event in
dsh-api-remotes. So a question asked without an agent never reaches the
browser — it falls through to noAnswerer and rejects with NO_PROVIDER.
But WebRuntime.fetch(request, signal) receives only { url } and a signal.
The agent is nowhere in that call, and WebRuntime is a root-level service, so
context probing cannot recover it either.
The agent loop publishes it exactly one layer up. ToolExecution.agent is
documented as "The agent on whose behalf the call runs (set by the agent
loop)", and tools/pre-execute is dispatched with
scopeTarget(this, exec.agent). So lib/agent-correlation.js observes that
event and remembers which agent owns each in-flight call.
The signal is not a reliable key, and this is the one place where the
obvious design is wrong. dsh-tool-web does hand exec.signal straight
through:
const result = await ctx.web.fetch({ url: input.url }, exec.signal);
but by the time the tool body runs, exec.signal is no longer the signal
tools/pre-execute saw. ToolRegistry.dispatchToolBody fuses the caller's
signal with whatever an around-wrapper installed and overwrites the field:
const wrapperSignal = exec.signal;
const fused = fuseToolSignals(state.callerSignal, wrapperSignal);
exec.signal = fused.signal; // ← a brand-new AbortController signal
const returned = await tool.execute(exec.arguments, exec);
// finally: exec.signal = wrapperSignal
fuseToolSignals returns the caller's signal unchanged only when
caller === wrapper. With any around-wrapper in play — and the real Web
deployment has one — the tool body receives a fresh signal that nothing outside
that call ever saw. Measured on a real run:
agent associated; matched by URL only (1 record(s), signal present);
scoped ask: NO_PROVIDER; unscoped ask: NO_PROVIDER
Identity missed while the call was plainly in flight. So correlation is two tiered, and the URL tier is the one that works:
A miss returns nothing, and the controller then reports the fetch as
unavailable (coded web_cloudflare_handoff_unavailable) rather than pretending
to have asked a question nobody saw. The coded message carries the
correlation diagnostic, so "the observer never fired" and "the observer fired
but no tier matched" are distinguishable without another restart — those two
faults used to look identical from the fetch side.
Two consequences worth knowing:
ask_user_question
instead.DELEGATED_CALLER. Falling
back to an unscoped question there would pop a question about a subagent's URL
into the parent's session, so that case is reported as unavailable rather than
quietly redirected.DSH has no browser, but the user is already running one — they are reading the DSH Web GUI in it. The handoff uses two real host capabilities, and neither is a browser control layer:
lib/native-open.js. On Windows that is
powershell.exe -NoProfile -Command "Invoke-Item -LiteralPath <path>", which
hands the file to the .html association → the default browser.The opener takes a path. On Windows it runs
powershell.exe -NoProfile -Command "Invoke-Item -LiteralPath <path>", and
Invoke-Item resolves its argument as a provider path. Measured on the target
machine:
| Argument | Result |
|---|---|
a real .html file | exit 0, silent, opens via the .html file association → default browser |
file:///C:/Users/.../x.html | Cannot find drive. A drive with the name 'file' does not exist. — exit 1 |
https://example.com | Cannot find drive. A drive with the name 'https' does not exist. — exit 1 |
A URL cannot be opened. So lib/browser-open.js writes a small local HTML page
that links the real URL (and, when autoNavigate is on, navigates to it
immediately), then opens that file. The staged page is created under the OS
temp directory with a dsh-cf-handoff- prefix and is removed by the plugin's
disposer.
openNativePathThe first version imported @deepseek-ai/dsh-native-command and called its
openNativePath. In the real deployment — a plugin installed with link: — that
throws on every handoff:
Error: Cloudflare challenge on https://community.cloudflare.com/ — the page content was NOT retrieved.
...
The browser could not be opened automatically (Cannot find package
'@deepseek-ai/dsh-native-command' imported from D:\桌面\工作区\dsh-cf-handoff\lib\index.js).
Bare-specifier resolution walks up from the importing file. A link:-installed
plugin sits outside the profile's node_modules, so the harness package is not
reachable from it; declaring it a dependency would only produce a second copy and
still not the profile's instance. The behaviour is therefore reproduced in
lib/native-open.js — twenty lines, no runtime dependency, same commands — and
test/acceptance-browser.mjs is what checks the replacement against this machine.
test/native-open.test.mjs pins the exact argument vectors so the table above
keeps applying to the shipped code.
Writing the replacement turned up a second measurement worth keeping. spawn
options change what "the launch failed" even means:
| spawn options | exit code for a URL argument |
|---|---|
stdio: 'pipe' | 1 (stderr carries Cannot find drive) |
stdio: 'ignore' | 1 |
stdio: 'ignore', detached: true | 0 |
detached: true looks like the harmless choice — "let the opener outlive the
caller" — and it silently turns a failed launch into an apparent success, so the
control assertion in test/acceptance-browser.mjs passed while no window opened.
The shipped opener does not detach, and a test pins options.detached to
undefined with that reason attached. It does not need to detach: it awaits the
launcher's exit, and the browser is started by the shell association, not by this
process.
Every failure path keeps the handoff alive, because the question itself always carries the URL:
openBrowser: false → no browser attempt at all;openBrowser: false; the user opens the URL from
the question card in whatever browser they have.A second handoff for the same URL within five minutes reuses the tab that is
already on screen instead of spawning another. That window exists because of what
the first real acceptance run looked like: the user cleared the check, chose
verified, the retry was challenged again (see §5.3 — that is expected), and the
next fetch opened a third tab for a page the user was already looking at. One
tab per page, not one tab per attempt. A different URL, or the same URL after the
window, stages its own page; reopenAfterMs: 0 disables the reuse.
Staged pages live in %TEMP%/dsh-cf-handoff-* (os.tmpdir() on POSIX) and are
removed when the plugin is disposed. A hard kill leaves the directory behind — it
is one ~2 KB HTML file, and the OS temp sweeper will eventually take it. If you
restart DSH a lot, sweep them yourself; the plugin deliberately does not delete
directories at startup, because a second running instance may have a live page in
there.
lib/cf-detect.js is pure, dependency-free, and I/O-free, so it is unit-testable
against recorded responses.
detectCfInterstitial({ statusCode, body }, { minScore }) // → { kind, score, signals, summary }
isCloudflareChallenge(html, url)
isCloudflareChallengeUrl(url)
couldBeCloudflareInterstitial(url, body)
Verdict kinds, ordered from "worth a human" to "not Cloudflare's doing":
| kind | meaning | handoff? |
|---|---|---|
challenge | an interactive interstitial a human can clear | yes |
block | Cloudflare refused outright (1020 / firewall rule) | no — no human clears it |
page-error | an edge error page that merely mentions Cloudflare | no |
none | no signal | no |
Scoring: each matching rule adds a weight; DEFAULT_MIN_SCORE = 12, and an
interstitial status code (403/429/503) adds a bonus only when the body
already carries a signal. Strong markers (_cf_chl_opt,
/cdn-cgi/challenge-platform) are worth 8–10; the phrasal evidence
(Just a moment..., checking your browser, Turnstile embeds) 6–8; weak hints
(Attention Required!) 4–5.
The tuning is not guesswork. Four real fetches, recorded while building this:
| URL | Response | Required verdict |
|---|---|---|
https://community.cloudflare.com/ | HTTP 403, body is the bare Just a moment... shell — no JavaScript runs, so only the title remains | challenge (scores 14) |
https://www.g2.com/ | HTTP 403, Please enable JS and disable any ad blocker | challenge |
https://developers.cloudflare.com/fundamentals/reference/error-codes/ | HTTP 404, a large real document that says "Cloudflare" hundreds of times | none — this is the false-positive test |
https://discord.com/api/v10/gateway | transport failure | not a Cloudflare matter |
The dangerous failure is stalling a turn on a page that never needed a human, so the rules are written to require structural evidence:
isCloudflareChallenge(html, url) returns true only for a challenge
verdict. The recall-oriented couldBeCloudflareInterstitial is a separate
function, so a URL-only hit can never be mistaken for a confirmed challenge.Feature lists age: Cloudflare changes its interstitial markup. Rules live in one
exported table at the top of lib/cf-detect.js; add an entry with a weight and
a kind, and cover it in test/detect.test.mjs. Prefer a structural
selector (an element id, a script path) over a sentence — sentences get
translated and reworded.
An in-call wait is the obvious design, and on web_fetch it does not work. The
first version of this plugin did exactly that, and a real GUI session produced
this instead of a question card:
Error: tool call timed out after 30000ms
The cause is a host row, @deepseek-ai/dsh-tool-call-timeout-policy:
// @deepseek-ai/dsh-tool-call-timeout-policy/lib/index.js:123-130
const timeoutMs = ctx.tools.get(exec.name, exec.agent)?.timeoutMs;
if (timeoutMs === void 0) return next();
const d = /* ... */ deadline(exec.signal, timeoutMs, TOOL_TIMEOUT) /* ... */;
if (timeoutOf(d.signal, 'TOOL_TIMEOUT') !== void 0) return toolTimeoutResult(timeoutMs);
toolTimeoutResult (:93-94) renders tool call timed out after ${timeoutMs}ms.
web_fetch takes its budget from fetchTimeoutMs, default
DEFAULT_WEB_TOOL_TIMEOUT_MS = 30000 (@deepseek-ai/dsh-tool-web/lib/index.js:850,
attached as ToolDefinition.timeoutMs at :801).
So 30 seconds is a hard ceiling, and exceeding it does not merely fail: the policy aborts the call and substitutes its own message, discarding whatever the plugin wanted to say — including the URL the user needs. A handoff that waits ~90 s for a person therefore produces strictly less information than no handoff at all.
ask_user_question is not subject to this, because @deepseek-ai/dsh-tool-ask-user
declares no timeoutMs and the policy returns next() for an undefined budget.
That asymmetry is the design:
mode | who waits for the human | when to use it |
|---|---|---|
notify (default) | nobody inside the fetch — the agent then awaits the human with ask_user_question, which has no budget | anywhere web_fetch keeps its default 30 s budget |
inline | the fetch itself, then retries once after the answer | only when the calling tool's budget is raised above minHumanBudgetMs |
In notify mode the fetch still does everything it can: it stages the bootstrap
page, opens the browser, and throws a coded notice carrying the URL and telling the
agent to await the human. It just refuses to be the wait.
inline mode is guarded rather than trusted. Before asking, it reads the budget the
policy will enforce and refuses to start a wait it cannot finish:
the tool call is budgeted at 30000ms but a human round trip needs at least 120000ms,
so an in-call wait would be killed by the timeout policy and its generic message
would replace this one (raise tool-web's fetchTimeoutMs to allow it)
Refusing early is strictly better than being killed mid-question, because an early refusal still carries the URL.
The table below lists inline mode's outcomes. In notify mode the fetch never
asks: it reaches the top of the table's report path and hands the human to the
agent.
| Situation | Behaviour |
|---|---|
| User says the check is clear | the same fetch call retries once; if the content now arrives, that content is returned |
| Still challenged after the retry | fails with code web_cloudflare_challenge and the URL, telling the agent the page is the verification step |
| User pastes the page content | returned immediately as a synthesized result — the network is not re-queried |
| User declines | fails with code web_cloudflare_handoff_refused and their reason |
| No answerer reachable | fails with code web_cloudflare_handoff_unavailable plus the URL |
| Cloudflare hard-blocks | fails with code web_blocked_by_cloudflare; the user is never asked, because no human action clears a firewall rule |
| Turn cancelled | ASK_ABORTED propagates untouched; staged files are cleaned up |
The retry budget is per fetch call (maxAttempts, default 1), so a page that
re-challenges cannot be reset into a loop by re-triggering the interstitial. A
budget of 0 is legal and produces a report-only plugin.
The distinction that matters: skip never yields empty content that the model
might misread as "the page was blank". Every non-recovery path is a coded
error carrying the URL.
Those codes are only useful if the agent actually sees them, and the first end-to-end run proved it did not. A thrown tool error reaches the model as the literal text:
// @deepseek-ai/dsh-tools/lib/index.js:3496
text: `Error: ${message}`
The code survives only as a structured field (result.error.info.code,
:3496–:3501); it is never interpolated into that text. Handed a real
challenge, the agent quoted this plugin's message and reported the inner
NO_PROVIDER as the failure code, because that was the only code-shaped string
it could see — web_cloudflare_handoff_unavailable was invisible to it.
So fail() in lib/provider.js appends the code to the message text as well as
setting it on the error:
const text = message.includes(code) ? message : `${message} [${code}]`;
Every documented code therefore appears twice: machine-readable on the error object, and readable in the text the model gets. The table above describes what the agent can actually read, which is the only version of that promise worth making.
The two headless runs, verbatim, are the whole argument — the only difference
between them is that one line of fail():
# before — asked for "its exact error code", the agent answered:
| `NO_PROVIDER` | … the harness-level code for the failed handoff |
# after — the same task, same site, same challenge:
Error: Cloudflare handoff could not reach the user: … [web_cloudflare_handoff_unavailable]
Notes for interpretation: … the bracketed tag `[web_cloudflare_handoff_unavailable]`
is the failure code.
Same detection, same fallback, same URL. The code became actionable only when
it moved into the text. test/acceptance-headless.mjs now asserts it stays there.
This layer does not transfer the clearance the human earned. It cannot:
dsh-web-fetch-http builds an Undici request with no cookie jar and no session
("Requests carry no browser cookies or ambient credentials"), and the
challenge clearance lives in a cf_clearance cookie plus a browser fingerprint,
in the user's browser profile — not in DSH. So the retry is a fresh, stateless
request that may itself be challenged again.
The README is explicit about this rather than hiding it, because it decides which answer the user should give:
Just a moment...
interstitials — will keep being challenged no matter how many times the human
clears it in their own browser.For the second case the paste path is not a fallback, it is the answer: the human
is already looking at the real page in the real browser, so the content they can
copy is content this layer can never fetch. The question is worded to make that
the obvious move ("paste the page content as your answer"), and
classifyPastedBody sends markup back down the same rendering path the network
result would have taken.
This is also why the plugin refuses to "solve" Cloudflare: a solver would have to forge exactly the fingerprint and cookie it is honest about not having.
The package ships its own cordis.patch.yml and declares dsh.bundle.patch, so
it mounts as a profile layer rather than needing a hand-written row:
dsh plugin add <path-or-tarball> --profile web
From a clone, that is just dsh plugin add ./dsh-cf-handoff --profile web; the
profile records the spec verbatim, so a link:-style development checkout keeps
picking up edits without reinstalling.
dsh plugin add reconciles dsh.profile.bundles against the installed state and
appends this package automatically, because the resolved manifest declares
dsh.bundle. Verify with:
dsh plugin list --profile web # dsh-cf-handoff must appear under bundles
If you would rather mount it by hand, the row is:
# profile cordis.patch.yml
- insert:
- id: cf-handoff
name: dsh-cf-handoff
The row needs no particular position: DSH activates rows by service
availability, and the plugin declares inject: ['web', 'userQuestions', 'tools'].
An id-targeted override replaces the row's config; it does not merge key by
key. Overriding only minScore in your profile layer therefore drops the other
keys back to the plugin's own schema defaults, not to the values in the bundle
layer. Restate every key you care about:
# profile cordis.patch.yml — headless deployment, all three keys restated
- id: cf-handoff
config:
minScore: 12
maxAttempts: 1
openBrowser: false
Every file in the layer is read live from the installed directory, so a link:
install needs no reinstall after an edit. A lib/*.js edit still needs a process
restart: patchReload: live reloads the patch layer, not the ESM module graph,
and Node caches imported modules for the life of the process. This one was learned
by measuring it — a diagnostic string added to handoff.js did not show up in the
next fetch until the process bounced, which is exactly the kind of "it must have
hot-reloaded" assumption this document exists to avoid.
| key | default | meaning |
|---|---|---|
enabled | true | master switch |
minScore | 12 | detection threshold; raise to 16+ for fewer handoffs, lower to ~6 for maximum recall |
mode | notify | notify = report and return, agent awaits the human; inline = wait inside the fetch (needs a raised tool budget — see §5.1) |
minHumanBudgetMs | 120000 | smallest tool-call budget an inline wait may start inside |
maxAttempts | 1 | handoffs allowed per fetch call; 0 = report only (inline mode) |
openBrowser | true | open a staged bootstrap page in the default browser |
autoNavigate | true | the staged page navigates to the URL on load instead of waiting for a click |
reopenAfterMs | 300000 | reuse the tab already open for this URL instead of staging another page (§3.2); 0 disables the reuse |
tmpRoot | OS temp | where staged pages are written |
Both modes stage and open the browser; the difference is only who waits.
tool-web composes web_fetch per agent preset, and the pentest preset ships
fetch: false. The plugin is preset-independent: with web_fetch off, nothing
reaches the seam and it stays idle.
| file | responsibility |
|---|---|
lib/index.js | Cordis plugin: config, wiring, lifecycle |
lib/cf-detect.js | pure detection — rules, scoring, verdicts |
lib/agent-correlation.js | remembers the agent behind each in-flight fetch, by signal then by unambiguous URL |
lib/agent-scope.js | scope probing, used as a fallback for agent recovery |
lib/browser-open.js | staged bootstrap page + opener call |
lib/native-open.js | the opener itself: platform "open with the default application" verbs |
lib/handoff.js | the pause: question construction, answer parsing, retry budget |
lib/provider.js | ctx.web.fetch decorator, error surface, disposer |
The split is deliberate: cf-detect.js is pure so detection can be tested from
recorded fixtures without a runtime, while handoff.js/provider.js own
everything that needs one. native-open.js is separate from browser-open.js
because only the former touches the host.
npm test # node --test "test/*.test.mjs" — 114 tests, no network, no runtime
npm run test:smoke # live wiring against the installed Cordis / WebRuntime / UserQuestionService
npm run acceptance:headless # a real headless DSH run against a real Cloudflare site
npm run acceptance:browser # the real opener on this machine — OPENS ONE BROWSER WINDOW
detect.test.mjs covers the four recorded real responses above, the
false-positive regression, URL markers, truncation, and rule weighting.
handoff.test.mjs covers answer parsing, pasted-body classification, question
construction, and the DELEGATED_CALLER / NO_PROVIDER branches.
provider.test.mjs covers the intercept end to end over a fake runtime: retry
budget, pasted short-circuit, coded failures, idempotent install, and disposal.
agent-correlation.test.mjs covers both correlation tiers, parallel fetches, the
ambiguity refusal, the aborted-call eviction, and the observer's disposer.
native-open.test.mjs pins the opener to the exact platform command vectors and
to the spawn options (stdio: 'ignore', no detached), so the §3.1 and §3.1.1
tables stay true of the shipped code — not just of the harness package it was
copied from. browser-open.test.mjs covers the bootstrap page (escaping, the
optional self-navigation, a hostile detection reason) and the tab-reuse rule of
§3.2, over an injected opener and a fake clock.
test/live-smoke.mjs is the one that matters for the claims this design rests
on, because the unit tests fake both sides of every seam. It loads the real
@deepseek-ai/cordis, dsh-web, dsh-user-questions and dsh-scope from the
installed profile and asserts:
ctx.web.fetch really is a replaceable own method on the live WebRuntime,
and the wrapper still runs dsh-web's own provider resolution.scopeTarget(agent, agent) really does admit an answerer registered on that
agent's scope, and carrierKeyOf on that carrier returns the agent — which is
what lib/agent-scope.js's fallback depends on.tools/pre-execute observed from a plain context really does reach the
correlation table, keyed by the signal the tool hands to web.fetch. If that
admission rule went the other way the observer would record nothing and every
handoff would degrade to "no answerer" — a failure that looks like the network,
not like a bug.Two facts it pinned down that a fake cannot show, both of which changed the code:
ask({ questions })
with no agent falls through to noAnswerer. This is why
lib/agent-correlation.js exists at all.exec.signal at tools/pre-execute is not the signal the tool body
receives. dispatchToolBody overwrites the field with a fused signal. This
is not visible from any seam above the tool body, which is why the code
shipped first with a signal-only key and then failed on a real page while
every fake-based test passed. Correlation now falls back to the URL, and the
coded failure reports which tier matched.request.questions arrives as the live service's own array proxy. Indexing
it works; reading named fields off the elements later does not. Anything that
wants to inspect a question must read it while the request is in hand.Neither the smoke test nor the unit tests reach the network or open a window;
openBrowser: false exercises exactly the headless path that must work with no
opener available.
CI (.github/workflows/ci.yml) runs npm test on Node 22 and 24, on both Linux
and Windows. Node 20 is deliberately out of the matrix: npm test hands a glob
to node --test, which Node 20 reads as a literal path
(Could not find '.../test/*.test.mjs') because glob expansion in the test
runner only arrived in Node 21 — and 20 is past end of life anyway.
The other three commands stay local by design: they need an installed DSH
profile, a real dsh binary, and — for the last one — a desktop session.
These are the only tests that use the real world. Both are opt-in because one spends model calls and the other opens a window.
test/acceptance-headless.mjs runs dsh --profile headless twice against
live sites — a guarded one that serves a genuine interstitial, and a plain one —
and asserts on what the agent could actually read. It needs the plugin installed
into that profile first (dsh plugin add <dir> --profile headless). A headless
run has no GUI answerer, so it exercises the branch that must report rather
than hang, and that is the only branch reachable without a human at the keyboard.
It is also the regression guard for §5.2 — remove the code from the message and
this script fails while every unit test still passes.
test/acceptance-browser.mjs calls the plugin's own shipped opener
(lib/native-open.js, the exact function lib/index.js wires) and opens one
browser window. It exists because every other test injects a fake opener, so none
of them show that "the user's default browser opens the blocked URL" is true of
the code that actually runs. It also asserts the control: handing a URL straight
to the opener fails, which is what pins the staged-file design to execution rather
than to reading. §3.1.1 explains why this file stopped importing
@deepseek-ai/dsh-native-command: the import is what failed in the real install.
One live round trip has now been done, by hand, in the Web GUI. It went: a
real web_fetch of a guarded site → challenge detected → a browser tab opened
from the staged page → the notice returned with the code and the URL → the agent
asked, with the URL as a clickable detail link → the human chose verified →
the retry ran → the retry was challenged again, which is exactly what §5.3
predicts for a stateless fetch. So the mechanical loop closes; what it cannot do
is carry a clearance it never had.
What that leaves unverified:
classifyPastedBody is covered by unit tests, but no live
run has pasted a real page into the answer box.test/provider.test.mjs) and ask_user_question with an
agent is proven to reach the Web GUI answerer (test/live-smoke.mjs); whether a
given model actually asks is not something a test here can force.test/live-smoke.mjs, never against a live site.inline mode's human round trip is likewise only partly observable from a script:
the plugin side is covered (ask → answer → retry), but a real clear requires a
page that stops challenging.
| path | role |
|---|---|
lib/ | the plugin (see §7) |
test/ | unit, smoke and acceptance suites (§8) |
cordis.patch.yml | the profile-layer row (§6) |
tsconfig.json | editor/opt-in JSDoc checking only — there is no build step, and TypeScript is not a dependency |
package.json | the dsh.bundle.patch declaration is what makes §6's one-liner mount the layer |
LICENSE | MIT |
All human-facing text is hard-coded English in 0.1.0. That is the obvious contribution if this is going to fit a non-English deployment, so here is the map.
| where | what | constraint |
|---|---|---|
lib/handoff.js buildHandoffQuestions() | the question's header, question, and the three option labels verified / paste / skip | the labels are the answer protocol — the GUI returns the selected label |
lib/handoff.js parseAnswer() | accepts those labels and tolerant synonyms (done, passed, ok, verified, skip, refused, …) | add translated labels here, keep the English ones. It already recognizes a few Chinese done words (完成 好了 过了 通过 重试) but no Chinese refusal words — that is the first gap to close |
lib/handoff.js classifyPastedBody() | decides whether a pasted body is a real page or a challenge again | it reads page structure, not language; no translation needed |
lib/handoff.js buildChallengeNotice() | the instruction the agent reads before it asks | model-facing, not human-facing — translate only if your models do better that way |
lib/provider.js | coded failure messages | the bracketed code must survive translation (§5.2) |
Two rules for a localization patch:
web_cloudflare_challenge,
web_cloudflare_handoff_refused, web_blocked_by_cloudflare and friends are
contract: the model reads them and test/provider.test.mjs matches them.detail carries the blocked URL as a markdown link, and the DSH Web GUI renders
markdown, so the click-through needs no translation at all.