agent.steer() from a plugin breaks the tool layer (reading 'kind') on 0.1.5-rc.1

[Meilin410]

Summary

Calling agent.steer(...) from a plugin on an agent reference obtained from the
agent/created event makes the tool layer fail for the rest of the run:

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

The steered message is delivered and consumed (a second turn/end appears
in the session log), but tool calls in that turn break. Plugin-driven steering
therefore looks like it works and then poisons the run.

A second, distinct error appears when steering synchronously from inside a
session/event handler:

Error: session append cannot reenter while another append is being published

Environment

dsh	0.1.5-rc.1 (latest dist-tag)
OS	Windows 11
node	v24.19.0
Profile	headless bundle (dsh-base + dsh-headless) + a few third-party plugins
Provider	DeepSeek official API (https://api.deepseek.com/v1)

What works (verified, in case it narrows things down)

1. agent/created fires under a headless run and its payload carries a usable agent:
   payloadKeys: ["agent"], and steer/followup/inject/whenIdle are all functions.
2. ctx.on("session/event", (session, event) => …) subscribes fine and turn/end is observable.
3. turn/start / turn/end are session events (session.append(...)), so subscribing via bare
   ctx.on("turn/start") never fires. (Not a bug — just easy to get wrong; may deserve a doc note.)

Reproduction

Attach this plugin to a headless profile, then run any task that uses a tool:

const name = "steer-repro";
const Config = z.object({ logPath: z.string().default("repro.jsonl") });

function apply(ctx, config) {
  let agent = null;
  ctx.on("agent/created", (p) => { agent = p?.agent ?? null; });

  // Variant A: steer inside the handler  -> "cannot reenter" error
  ctx.on("session/event", (session, event) => {
    if (event?.type !== "turn/end") return;
    agent?.steer({ role: "user", content: [{ type: "text", text: "Also reply with exactly: STEERED_OK" }] });
  });

  // Variant B: defer out of the publish frame -> steer consumed, tools break
  // setImmediate(() => agent?.steer({ ... }));

  // Variant C: poll session.ownEvents()/eventAt() with no subscription at all
  // setInterval(() => { /* on turn/end, then agent.steer(...) */ }, 400);
}

export { Config, apply, name };

Result for all three variants:

$ dsh --profile <bee> "Reply with exactly: BASE"
BASE
dsh: UNKNOWN: Cannot read properties of undefined (reading 'kind')

Isolation

Variant	Result
subscription present, but never steer	baseline completes normally
steer synchronously inside session/event	session append cannot reenter while another append is being published
steer via setImmediate (out of publish frame)	steer delivered (second turn/end), tools then break
steer via pure polling, no event subscription	tools break
plugin detached (control)	normal

So the crash tracks the steer() call itself, not the subscription and not the
deferral mechanism. --dump-config and boot are clean in every case, i.e. this
is not a plugin-loading problem.

Hypothesis

steer() re-enters the agent step loop while the tool scheduler's state is
mid-publish, so the scheduler resolves a tool record that is undefined
(reading 'kind' is the signature of a failed scheduler-record lookup). This
resembles the earlier tool-layer failures where a second copy of
@deepseek-ai/dsh-tools splits the module-local Symbol used as the scheduler
key (the #1337 / #4640 / #4667 family) — as if the injected step resolves the
scheduler against a different instance than the one the running turn publishes to.

Impact

Any plugin-driven steering is unusable, which is the natural way to correct a
long-running headless task without running a resident Host. Users are left with
only cancellation/timeout, losing the ability to redirect a task mid-flight.

Requests

1. Make steer() safe to call from a plugin callback, or document the required
   call context (which frame/lifecycle it must run in).
2. If re-entrancy is inherently unsafe from inside session/event, raise a clear
   error at the steer() call site instead of corrupting the tool layer for
   the remainder of the run.
3. If this is the known Symbol-split family, does the Symbol.for fix cover the
   steer path?

Deterministic locally (5/5 runs). Minimal repro plugins and the JSONL logs showing
the steered message being consumed immediately before the tool failure are
available if useful.

[argszero]

Thanks for the very carefully isolated report — the variant table (subscription present/absent, sync/deferred/polling, detached control) is what made this answerable from source. I read the driver, the tool scheduler, and the session append path on 0.1.5-rc.2 / master c291e7961a and have one mechanical answer for your question 3, plus a hazard you did not list.

Q3 — no, this is almost certainly not the Symbol-split family

I could not confirm your hypothesis from the code, and I think your own earlier report is the discriminator. In the duplicate-copy family (your own #6416), the first failure is Cannot read properties of undefined (reading 'prepare'), because dsh-agent-loop dereferences the scheduler object before any tool body runs:

• packages/core/agent-loop/src/tool-calls.ts:153-154 — ctx.tools[TOOL_RUNTIME_SCHEDULER].finalize/finish
• :170 — ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare
• packages/core/tools/src/ptc.ts:480 — const scheduler = registry[TOOL_RUNTIME_SCHEDULER]

If the loop's instance and the dispatched instance had split, you would get reading 'prepare' (or finalize) first, not reading 'kind' — steer() does not touch the tool layer at all (agent.ts:141 → :129 this.inbox.splice(target, Infinity, 0, …) → wakeDriver). steer() cannot itself resolve a scheduler.

I also went looking for the dereference that produces reading 'kind' and could not find one reachable from this path. Every .kind site in dsh-tools is type-guarded on a value this registry minted moments earlier (createExecution returns only final-result / ready at packages/core/tools/src/index.ts:1354-1441; the non-optional sites are :1337, :1340, :1458, :1469, :1476, :1738). assertNever cannot fire with undefined — it stringifies the value instead of dereferencing it (packages/util/values/src/index.ts). So I do not think the crash is a null lookup in the scheduler record at all; I think it is a class-identity split (a different copy of the objects crossing the seam), which is the same family as #6416 but not the same site.

Two things would settle it, and neither needs a guess:

1. the full error stack (the UNKNOWN: prefix means this was flattened through errorChain at packages/core/agent-loop/src/agent.ts:328-333 — the original stack still existed at that point);
2. Object.keys(require('node:module')._cache) / process.moduleLoadList, or simply the number of physical @deepseek-ai/dsh-tools directories under your profile tree. If there are two, then your profile has the [dsh] profile 内出现第二份核心包 → Symbol/instanceof 跨实例失效 → 工具派发崩溃（reading 'prepare'） #6416 condition and the crash is downstream of it.

One concrete candidate I did verify: a message without source

createUserMessage does not default source (packages/llm/llm/src/message.ts:204-211 — it forwards only role: 'user'), so a plain JS plugin calling agent.steer({ role: 'user', content: [...] }) produces a message whose source is undefined. Two sites dereference it without a guard:

• packages/core/agent-loop/src/runtime-context.ts:18 — message.source.kind === 'plugin' && …
• packages/api/session-controller/src/control.ts:187 — message.source.kind === 'user' ? 'steering' : 'context'

Cannot read properties of undefined (reading 'kind') is exactly what those produce. If your repro was close to the JS snippet in the report (and not the TypeScript schema-validated one), check this first — it is a one-character fix on your side and needs no harness change. If your messages do carry source, then ignore this paragraph; it is an addendum, not my main answer.

Q1 — what the contract actually says, and where it is genuinely thin

steer() is fire-and-forget by design: it enqueues into next-step and wakes the driver (agent.ts:141, :129, :187). There is no promise to await and no "steer completed" event — the documented contract is only "the running driver consumes it at its next step boundary" (packages/core/agent/src/runtime-types.ts:231). The only producer-side hazard I found is this one, and it is worth calling out because it is silent:

If the driver has already decided to end the turn and no further step boundary will open, the steering is never consumed — it is recorded (agent/inbox/spliced, durably) and reported as steering in the queue, but turn() returns false when !inbox.hasPending, and the splice observers have already run. In your Variant B the second turn/end did appear, so this is not what you hit; it is the adjacent sharp edge.

★ The hazard you did not list: addition at the tail of next-step

This is my main finding, and I think it explains how a crash could look steer-shaped.

• steer() inserts with index Infinity (agent.ts:129), which clamps to the inbox length — i.e. after everything already queued in next-step.
• But a tool result's deferred context is appended there too, during the same step, by packages/core/agent-loop/src/agent.ts:490 (inbox.splice('next-step', this.inbox.nextStep.length, 0, [context])), carrying e.g. the PTC image/context messages built at packages/core/tools/src/ptc.ts:562.
• The boundary then claims the whole batch — claim() removes next-step[0 .. length) (packages/core/agent-loop/src/inbox.ts:111-116).
• So a steer that lands during the window between a tool's commit and the next boundary is appended after that committed context, and the model receives it after the tool result instead of before — and the tail insertion can be swallowed by the claim while the caller has already observed agent/inbox/claimed and the durable splice.

The reason I am not proposing a patch: this ordering is pinned as expected behaviour by the harness's own tests — packages/core/agent-loop/tests/inbox.spec.ts:129-155 asserts that inherited/pending input precedes the claimed batch and that a steer preserves its source (tests/contract-regressions.spec.ts:475-515). Changing it is a deliberate ordering decision for the maintainers, and it needs a side registry of live inbox objects to be done safely — a static WeakMap in a module cannot enforce anything when a second copy of dsh-tools/dsh-agent-loop is in play (your #6416 condition). I am flagging it rather than pretending it is a one-liner.

Q2 — the honest answer

I cannot show you a throw for a re-entrant steer(), and I will not invent one: today it degrades silently instead. What I can show is why the sync variant fails loudly and the deferred one does not — packages/core/session/src/index.ts:730 throws session append cannot reenter while another append is being published, and a listener that observes turn/end is by definition inside that publish frame (appending is the publish). That is a deliberate guard (core/session/tests/session.spec.ts:1679), not a bug, so the "raise a clear error at the call site" half of your request is really "state the required call context in the JSDoc" — the steer doc comment currently does not mention frames at all. That part is a one-line documentation fix and worth filing on its own.

Boundary disclosure

• I did not reproduce this: no Windows, no dsh install, no plugin profile here; my conclusions are source-level reads of 0.1.5-rc.2/master.
• I confirmed the published artifacts for dsh-tools/dsh-agent-loop are byte-identical between 0.1.5-rc.1 and 0.1.5-rc.2 (lib/index.js diff is empty), so your observation living on both is expected — the sources did not change between them.
• I am not a maintainer and I am not speaking for the project. If it helps, I can put the tail-ordering observation plus the repro table into a small plugin that logs (message.id, placement, source.kind, seq) at the boundary so the crash lands next to the evidence — that is a diagnostic, not a fix, and I would only build it if you think the extra signal is worth it.

[PerryLink]

核实结论:崩溃是「steer 注入裸对象(无 source)」触发,不是 scheduler/Symbol 分裂;Q3 答案为否.

1. steer 是 fire-and-forget:消息以 Infinity 插入 next-step 尾(agent-loop/src/agent.ts:128-147)并唤醒 driver(:187),契约只写「最近一步边界消费」(agent/src/runtime-types.ts:225-231),未声明调用帧限制.
2. 变体 A 重入属实:steer 内部要 append agent/inbox/spliced(inbox.ts:238),在 session/event 监听器内调用正处 publish 帧,撞 core/session/src/index.ts:730 守卫(文本逐字一致;session.spec.ts:1679 有测试). 监听器异常被 contained(index.ts:402-420),故变体 A 响亮但无害,变体 B/C 的 UNKNOWN 才是主伤.
3. 'reading kind' 来源:createUserMessage 不默认 source(llm/src/message.ts:204-211),原帖 steer 的裸 {role,content} 无 source. claim→pre-step 沿路多个已发布插件无防护读 message.source.kind,任一先炸即 TypeError,经 turn() 的 errorChain 变 'dsh: UNKNOWN: …'(agent-loop/src/agent.ts:322-335):tool-jobs:227(agent/inbox/claimed)、repeat-tool-reminder:230、agent-instructions:51、tool-cordis:504、session-reference:159(agent/pre-step 瀑布,异常传播)、control.ts:187;runtime-context.ts:18 同型但被 contained. 谁先炸取决于 profile 装载,与「三变体都崩」一致. 此点比 agent.steer() from a plugin breaks the tool layer (reading 'kind') on 0.1.5-rc.1 #6451 评论1(argszero)的 control.ts:187/runtime-context.ts:18 两处更全.
4. 原帖假设不成立:tool 层 .kind 均在注册表刚铸造的联合值上(tools/src/index.ts:1337,1340,1458,1469,1476,1738);scheduler 缺失先炸 'prepare'/'finalize'(tool-calls.ts:153-154,170),steer 不触碰注册表(agent.ts:141-143).
5. rc.1 与 master 无差异:git diff 显示相关文件在 rc.1→rc.2(仅 package.json)与 rc.1→master(仅 README/测试)均未变,问题原样存在.
6. 修复:①调用方用 createUserMessage 并显式带 source(仓内测试契约即如此);②防御面:send()/createUserMessage 默认 source,或给上述监听器加守卫;③steer JSDoc 注明不可在 append 发布帧内同步调用. steer 落在 deferred context 之后(agent.ts:490)属既有契约(inbox.spec.ts:129-155),与本 bug 无关.