First tool call in a fresh session can crash with TypeError: Cannot read properties of undefined (reading 'prepare') — ctx.tools not yet initialized, and it doesn't self-recover

[mikeBehar]

Environment: deepseek-harness cloned from main, pnpm@11.7.0, Node v22.23.1, Windows 10, deepseek-official provider / deepseek-flash model.

Symptom: The first tool call of a session can fail immediately with:

TypeError: Cannot read properties of undefined (reading 'prepare')

This showed up in the Web GUI (dsh web) on the first message of a session shortly after the server had (re)started.

Update: this is not a brief transient race. Retrying the same failed message in the same session did not recover. Starting a brand-new session and waiting a full minute before sending the first prompt also did not recover — same crash. So whatever left ctx.tools (see root cause below) unpopulated appears to persist for the remaining lifetime of that server process, not just for a short warm-up window.

Reproduction (100% reliable): dsh --profile headless "what is the content of the file test.txt" run in a fresh workspace directory containing test.txt fails on essentially every invocation, because headless mode goes from process boot straight to the first LLM call/tool call with almost no warm-up time.

Root cause: Traced the real stack trace (by temporarily logging the caught error in packages/core/agent-loop) to:

at startCall (.../packages/core/agent-loop/lib/index.js:586:60)

which is:

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

TOOL_RUNTIME_SCHEDULER is a readonly instance field always present on the dsh-tools plugin object (packages/core/tools/src/index.ts:798), so it can only read as undefined if ctx.tools itself hasn't been registered into the context. Given it doesn't self-resolve even after a minute and a fresh session, this looks less like a slow-warm-up race and more like the dsh-tools plugin silently failing to initialize/register for the rest of that process's life (possibly swallowing an error during its own startup) rather than merely being delayed.

Impact: Once triggered, every session against that running dsh web process seems to hit the same failure on its first tool call. The only untested next step on our end would be fully restarting the dsh web process — haven't confirmed whether that clears it or whether it's more deeply state-dependent (e.g. tied to something in ~/.dsh).

Happy to share the full stack trace, the session logs, or a minimal repro script if useful.

[mikeBehar]

Update: this does not reproduce on the dsh-v0.1.5-rc.2 release tag.

I switched the checkout from main (0.1.6-alpha.2) to the dsh-v0.1.5-rc.2 tag, did a clean pnpm run clean && pnpm install && pnpm run build, and ran the same dsh --profile headless "what is the content of the file test.txt" repro against 3 separate fresh workspace directories. All 3 succeeded (exit code 0, correct file content returned) — versus 0/2 on the alpha build with the identical setup.

So this looks like a regression introduced somewhere between 0.1.5-rc.2 and 0.1.6-alpha.2, rather than a long-standing issue. Might help narrow down the bisect range.

Two incidental CLI differences noticed between the versions while testing, in case they're relevant:

• rc.2's headless profile requires --profile headless "task" explicitly; the main branch accepts the bare headless "task" shorthand.
• rc.2's headless profile doesn't support a --json structured-output flag; main does.

[argszero]

Your bisect boundary is right, and it is one commit wide — the answer is not a range.

The regression is a single line, and only 0.1.6-alpha.2 contains it

Moving from main to dsh-v0.1.5-rc.2 crosses exactly one change that ever shipped in the alpha line:

9ddef327a4 "feat: resolution mode link to runtime" (2026-09-17 19:52 +0800) flipped one default in apps/cli/src/profile-boot.ts:

- const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'link'
+ const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'

Tag containment (git tag --contains 9ddef327a4) yields dsh-v0.1.6-alpha.2 and nothing else: dsh-v0.1.6-alpha.1 does not contain it, and no 0.1.5 tag does. So the boundary is alpha.1-clean → alpha.2-broken, with no interval to bisect — worth one run on dsh-v0.1.6-alpha.1 to confirm it from the other side.

Why it is not a warm-up race, and where undefined comes from

TOOL_RUNTIME_SCHEDULER is a module-level unique symbol (packages/core/tools/src/index.ts:463), and the field it names sits on the tools plugin object (:798). The loop reaches it through the import at packages/core/agent-loop/src/tool-calls.ts:17 and dereferences it at :170 — the line in your stack trace.

ctx.tools is registered. What is undefined is the symbol lookup on it, because the object the loop reaches is a different evaluation of @deepseek-ai/dsh-tools than the one that installed the scheduler. Two evaluations of that module produce two distinct symbols, so the second instance has no [TOOL_RUNTIME_SCHEDULER] property at all. That is structural, hence permanent for the life of the process and independent of session — which is exactly what you measured: no recovery on retry, on a fresh session, or after a minute of warm-up. Nothing is racing; nothing was ever going to warm up.

resolutionMode: 'runtime' is what lets the two evaluations coexist: it changes how profile modules are resolved for a source launch (the parent path tsx sees for a runtime-resolved module is a node_modules symlink path, so the tsconfig-paths rewrite that normally keeps in-tree src/ requests and resolved lib/ requests on one identity no longer applies). The duplicate instance is the consequence, and the symbol is where it becomes visible.

Why the desktop app is fine and a source dsh launch is not

The flip touched two hosts, and only one half was reverted 55 minutes later (d9a55c7c0d). At HEAD:

• apps/cli/src/profile-boot.ts:263 — const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime' (still flipped)
• apps/desktop-host/src/index.ts:21 — resolutionMode: process.argv[5] === 'runtime' ? 'runtime' : 'link' (reverted to link)

apps/cli/src/bin.ts never passes resolutionMode, so a source CLI launch has no flag and no environment variable that can select the mode — the default is what you get. Same build, two hosts, different behaviour: that asymmetry is the signpost, and it also explains why packaged ? does not save you (a source launch is not packaged).

Workarounds

Run from dsh-v0.1.5-rc.2 as you already validated, or locally revert apps/cli/src/profile-boot.ts:263 back to ?? 'link' in your checkout — one line, and it restores the tsx-friendly resolution for source launches. Please do not commit that; it is a workaround, not the fix.

Same defect as the duplicate-dsh-tools cluster

This is the mechanism behind the other Cannot read properties of undefined (reading 'prepare') reports; see #7293, where two consequences are worked out: the failing batch path drains with group.slice(started) while started is incremented before the throwing await, so the culprit call is skipped rather than answered; and the generalizing arm is to make the marker survive a second module evaluation (Symbol.for) instead of minting a fresh unique symbol, so both evaluations agree on identity. Reporting this as "ctx.tools not yet initialized / no self-recovery" points at the wrong layer — the title would be better as "duplicate dsh-tools instance splits the module-level scheduler symbol".

The two CLI deltas you noticed between rc.2 and main (the --profile headless shorthand, the --json flag) are unrelated to this crash.

[mikeBehar]

Thanks for the very complete and informative reply. For now I'll stick with dsh-v0.1.5-rc.2 using Creator mode. For my tasks it is working great (so far).