--profile headless crashes on any tool call: "Cannot read properties of undefined (reading 'prepare')" (0.1.1-rc.2)

[sirendhead]

Issues are disabled on the repo, so posting here as the README suggests.

Symptom

With --profile headless, every turn where the model calls a tool dies with:

dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare')

The same setup, same command, same session — but a task phrased so the model answers without any tool ("reply with exactly PONG, do not use tools") — completes normally and exits 0. So the model/provider path is healthy; the failure is on the tool path.

Environment

• @deepseek-ai/dsh@0.1.1-rc.2 (current latest at time of writing)
• Node 25.5.0, Windows 11
• Launched via npx -y @deepseek-ai/dsh@0.1.1-rc.2 --profile headless --patch <overlay> "<task>"
• Model reached through an OpenAI-compatible endpoint via DEEPSEEK_BASE_URL

What I ruled out

Not caused by a third-party plugin. I first hit this with a hooks bridge plugin mounted, so I re-ran the identical tool-using task with a patch overlay that mounts no third-party plugin at all — same crash, byte-identical message. That control run is why I'm reporting it here rather than debugging my own plugin.

Not dsh-session-query-sqlite being mounted with openAt: never. That was my first hypothesis, since the docs say a search under that setting should fail with a typed SESSION_QUERY_SEARCH_DISABLED rather than crash. I overrode it to openAt: first-search with a real database path — no change, same crash. Recording this so nobody re-tests the same dead end.

Where I think it comes from

Grepping the installed bundle for .prepare( call sites, the candidates are:

• scheduler.prepare( in dsh-tools — best fit, since the failure is specific to the tool path
• persistence.prepare() / ctx.sessions.prepare() in dsh-agent-loop

Reading undefined.prepare suggests an optional dependency that the tool path assumes is present. dsh-session-persistence is declared optional (peerDependenciesMeta), so one plausible shape is: the headless profile does not mount it, and something on the tool path dereferences it unguarded instead of degrading.

Question for maintainers: is --profile headless expected to run tool calls out of the box, or does it require mounting an additional plugin (session persistence or similar)? If the latter, a typed error naming the missing capability would save a lot of guessing — right now it surfaces as an UNKNOWN TypeError.

Secondary: headless has no way to self-diagnose this

dsh-headless prints error.message only. No stack trace, and --help exposes no log/debug/verbose flag I could find. With an UNKNOWN TypeError and no frame, there is nothing for a user to act on — I had to grep the shipped bundle to form even a guess.

Two small things that would have turned this into a five-minute fix on my side:

1. Print the stack (or gate it behind --verbose / a DSH_LOG_LEVEL env var) when the error is not a typed harness error.
2. When a turn aborts hard, the session log persists only the event header — the event flush does not appear to complete, so post-mortem inspection of the session file shows almost nothing. Flushing pending events on abort would make crashes debuggable after the fact.

Happy to run any additional repro or provide the patch overlay if useful.

[Mide69]

Checked both of your candidate call sites in the source.

ctx.tools[TOOL_RUNTIME_SCHEDULER] is a plain class property set to a real object right on the tools registry itself (packages/core/tools/src/index.ts:796). It is not optionally registered and does not depend on any plugin being mounted. So if ctx.tools exists at all, that scheduler object should not be undefined. This makes your first guess unlikely to be the real cause.

Your second guess does not hold up either. dsh-base's cordis.patch.yml mounts session-persistence-jsonl unconditionally for every profile, including headless. So session persistence should be present by default too.

Neither lead points to an obvious missing plugin. Your own idea, printing the real stack trace behind the UNKNOWN error, is probably the fastest way to actually find this, since right now it is not clear which prepare() call is the undefined one.

[gitsult4n]

yes headless runs tool calls out of the box
nothing extra to mount

your persistence hunch is out
dsh-base already mounts session-persistence-jsonl and session-query-sqlite under it -> packages/bundle/base/cordis.patch.yml:98 and :117
and a missing persistence backend raises a named error rather than a bare deref -> packages/core/agent-loop/src/index.ts:656

what dies is this

const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)

packages/core/agent-loop/src/tool-calls.ts:169

TOOL_RUNTIME_SCHEDULER is a plain Symbol() and not Symbol.for() -> packages/core/tools/src/index.ts:466
so a second copy of @deepseek-ai/dsh-tools in the module graph hands dsh-agent-loop a different key than the one the live ToolRuntime installed -> packages/core/tools/src/index.ts:796
the lookup reads undefined and you get your exact string

reproduced on a clean 0.1.1-rc.2 install against a mock OpenAI-compatible endpoint that forces one tool call

• clean profile -> the read call runs and the turn completes
• copy dsh-tools into $DSH_HOME/profiles/headless/node_modules/@deepseek-ai/ -> dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare') on the tool turn while reply with exactly PONG still completes normally
• delete that copy -> tool calls work again

so check here assuming the default home

%USERPROFILE%\.dsh\profiles\headless\node_modules\@deepseek-ai

any dsh-* sitting in there is the duplicate and removing it should clear this
the profile own node_modules wins over the launcher flat fallback in the Node parent walk -> packages/boot/app-boot/src/profile.ts:208

guess and not verified -> how it landed there
dsh plugin does run pnpm with cwd set to the profile dir -> apps/cli/src/plugin.ts:130
but the generated profile sets autoInstallPeers: false -> packages/boot/app-boot/src/profile.ts:142 and harness packages name dsh-tools as a peer only
so an npm install or pnpm add run by hand in that directory is a likelier source than dsh plugin

on diagnostics you are right
packages/bundle/headless/src/index.ts:131 prints code and message only and a grep for DSH_LOG or any log level seam finds nothing in the tree

[sirendhead]

Confirmed on both counts — thank you, that was fast and exactly right.

The duplicate existed. ~/.dsh/profiles/headless/node_modules/@deepseek-ai/dsh-tools — pulled in as a peer when I installed dsh-hooks-claude-code into the profile home (npm ≥7 auto-installs peers on a standalone install, so the bridge's whole peer set got duplicated there). The bridge never imports dsh-tools at runtime (grepped its lib/ — zero hits), so the copy was dead weight poisoning the module graph.

Fix verified: renaming that one directory away, same command, same patch — the tool-using task now completes, exit 0, model returns the file contents. So my earlier control run was flawed: I had unmounted the plugin but left the packages on disk, which is why the crash "survived without the plugin". The Symbol() (vs Symbol.for()) sensitivity to a second copy is still worth hardening on your side, but the detonator was my install method.

For anyone else who lands here: if you install any plugin into a profile home with plain npm install, check node_modules/@deepseek-ai/ for duplicated core packages afterwards — one stray dsh-tools is enough to kill every tool call with this exact message.

One follow-up question, since the tool path now works: with --profile headless in one-shot mode, I can't observe the CC-bridge firing any hook events. Instrumented probes on UserPromptSubmit and on PreToolUse (matcher Write|Edit) both stay silent through fully successful turns — including a turn where the model creates a file, which on Claude Code would trigger the PreToolUse matcher. Are bridge hook events expected to fire on the headless one-shot path at all, or only in interactive/web sessions? If one-shot is expected to emit them, I'm happy to file a separate discussion with the repro.

[gitsult4n]

Great plz mark my post as answer 🤍🌷