Proposal: add agent/turn-starting and agent/turn-aborting hooks for turn-boundary observability

[liuyang0508]

---

TL;DR

Add two new plugin hooks to the agent loop so other plugins can observe turn boundaries without subscribing to step-level events and reconstructing turn boundaries themselves. No behavior change to existing events, session log shape, or turnEnds semantics. Three vitest fixtures demonstrate the new contract.

---

Background

Today ReactLoopAgent.turn() fires one turn-level event — agent/turn-stopping — right before a turn ends naturally. There is no symmetric hook at turn start, and no hook fired in the abort path.

Plugins that want turn-level visibility today have to subscribe to step/start, step/end, and reconstruct turn boundaries themselves. This couples plugin code to internal step ordering, which the AGENTS.md warns against ("Plugins, not loop changes").

The two new hooks fill this gap.

Proposal

New hooks

Hook	Type	Payload (declared)	Payload (delivered to listener)	Fires when
agent/turn-starting	serial	{ agent: Agent; turn: number; signal: AbortSignal }	same — agent injected by dispatcher	After the first preStep claim (which transitions the turn from idle to running) and phase.turn = turn, before the first step/start log entry — i.e. on the first iteration of the step loop, gated by target === 'next-turn' && step === 1
agent/turn-aborting	serial	{ agent: Agent; turn: number; cause: AgentCancelCause; signal: AbortSignal }	same — agent injected by dispatcher	Inside the catch block when signal.aborted is true, immediately before throw error

The agent field is declared in the payload type but is auto-injected by the fused dispatcher (AgentEventDispatch in packages/core/agent/src/dispatch.ts) — mirrors every existing agent/... event. This is the convention: declared shape matches delivered shape.

Both hooks use serial semantics (mirror the existing agent/turn-stopping): plugins observe synchronously, but cannot veto the turn. Plugins that want to "refuse" a turn throw from inside the listener; plugins that want to cancel mid-turn call agent.cancel(cause) using the agent field injected into the payload.

Where the hooks fire (in source order)

In packages/core/agent-loop/src/agent.ts, the current turn() flow becomes:

1. phase.kind === 'running' 断言
2. signal.throwIfAborted()
3. turn = phase.turn + 1
4. session.append('turn/start', { turn })          [既有]
5. phase.turn = turn                                [既有]
6. while (true) {
     a. preStep(turn, step)                         [既有 — 同步 claim]
     b. ► if (target === 'next-turn' && step === 1)
          dispatch.serial('agent/turn-starting', ...)  [新增 — fires once per turn]
          signal.throwIfAborted()                      [新增]
     c. step(start)                                 [既有]
     d. ...
   }
7. catch {
     if (signal.aborted) {
       ► dispatch.serial('agent/turn-aborting', ...)  [新增, before throw]
       turnEnds = { kind: 'aborted', reason }
       throw error
     }
     // ... 非 abort 错误路径不变 ...
   }
8. finally { session.append('turn/end', ...) }     [既有]

Note on placement: agent/turn-starting is fired on the first iteration of the step loop (gated by target === 'next-turn' && step === 1), not at the literal point between step 5 and 6 above. Rationale: preStep() (step 6a) performs a synchronous claim of the next proposed step — agent.followup(...) and agent.steer(...) rely on this synchronous claim semantics to keep their cancel / status transitions race-free. Placing the await dispatch.serial(...) between step 5 and step 6 would insert an await microtask boundary before preStep.claim(), which would break two existing tests (cancel.spec.ts:75 "does not restore work already claimed by a waking send" and loop.spec.ts:587 "starts idle steering synchronously"). The implementation instead fires the hook after the first preStep claim and before the first step/start log entry — the observable semantics are identical (fires once per natural turn, after phase.turn = turn, before any model work).

Why serial, not waterfall

waterfall lets listeners veto by not calling next(). For "veto turn start" this is too strong — a plugin that forgets to call next() would silently kill every turn. serial is observation-only and matches the existing agent/turn-stopping precedent.

Plugin-initiated abort is not a feature of these hooks. If a future need appears, it should be a separate agent/turn-cancel-request waterfall event with explicit veto semantics.

Files touched

File	Change
packages/core/agent-loop/src/agent.ts	Add 2 private methods (emitTurnStarting, emitTurnAborting); call them at 2 insertion points in turn() and 1 insertion point in the catch block. Method shape matches the existing emit('agent/error', ...) style.
packages/core/agent/src/runtime-types.ts	Add 2 entries to the interface Events declaration-merge block. JSDoc follows the existing agent/turn-stopping template: @mode serial, @param payload.agent, @param payload.turn, @param payload.signal, plus the "Scope-filtered dispatch (@deepseek-ai/dsh-scope): agent-scoped listeners receive only that agent." line.
packages/core/scope/src/scoped-events.generated.ts + packages/extensions/tool-cordis/src/api-catalog.ts	Auto-regenerated from pnpm run gen-scoped-events and pnpm run gen-cordis-catalog.
docs/subsystems/core.md + docs/subsystems/core.zh.md + docs/subsystems/core.i18n.yaml + docs/event-producer-consumer.md	Auto-regenerated from pnpm run gen-doc-graphs. The agent-loop events table and producer/consumer mapping gain two rows.
packages/core/agent-loop/tests/loop.spec.ts	Append 4 new vitest fixtures (see Test Plan)

No changes to preStep, step, buildRequest, tool-calls, kick, inbox, or session schema.

Error handling guarantees

Three throw paths through the new hooks, each with a defined outcome:

1. Plugin throws inside agent/turn-starting — falls through to the existing error path. turnEnds = { kind: 'error', error: { message, code: 'UNKNOWN' } }. agent/error fires. agent/turn-aborting does not fire (not an abort). Session log records the full turn with reason error.

2. Plugin throws inside agent/turn-aborting — caught locally, re-emitted as agent/error, not rethrown. The original error from the catch (the abort) continues to propagate. This is required so a misbehaving listener cannot mask the abort cause.

3. External abort arrives during agent/turn-starting — the signal.throwIfAborted() after the hook throws. catch enters the aborted branch. agent/turn-aborting fires with the abort cause (this is the intended "abort lifecycle closes" path).

The code shape for path 2:

} catch (error: unknown) {
  if (signal.aborted) {
    try {
      await this.dispatch.serial('agent/turn-aborting', {
        turn, cause: signal.reason as AgentCancelCause, signal,
      })
    } catch (listenerError) {
      this.dispatch.emit('agent/error', {
        turn, step: phase.step, error: listenerError,
      })
    }
    turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause }
    throw error
  }
  // ...
}

Behavior guarantees

What stays the same:

• Every existing event still fires at the same point with the same payload.
• Session log shape unchanged.
• turnEnds sticky max-tokens semantics unchanged.
• kick() loop termination unchanged.
• Public cancel() API unchanged.

What's new:

• Two new event keys in the dispatch map; subscribers via ctx.on('agent/turn-starting', ...) / ctx.on('agent/turn-aborting', ...) get type-complete payloads after the declaration-merge update.
• Plugins listening to these hooks must be tolerant of being called once per turn.

Test plan

Three vitest fixtures appended to packages/core/agent-loop/tests/loop.spec.ts. Each follows the existing harness() + MockAdapter + ctx.on('agent/status') pattern.

Fixture 1 — turn-starting fires exactly once per natural turn

Setup: a MockAdapter returning one text response. A listener subscribes to agent/turn-starting and records turn numbers. Send one message, wait for idle.

Asserts:

• Listener was called exactly once, with turn === 1.
• Adapter received exactly one model request.
• Final turn/end event has reason.kind === 'completed'.

Proves: hook position is correct (between turn/start and first step); one fire per turn (not per step).

Fixture 2 — turn-aborting carries the cancel cause before rethrow

Setup: a MockAdapter that returns the 'hang' marker (a response the adapter never resolves — lets the turn enter its first step and park there). Listener subscribes to agent/turn-aborting and records cause. Send a message, yield ~30 ms so the turn reaches its first step and agent.status is running, then call agent.cancel({ kind: 'user' }). Wait for idle.

Asserts:

• Listener was called exactly once, with cause === { kind: 'user' }.
• Final turn/end event has reason.kind === 'aborted'.

Proves: external cancel → abort signal → catch aborted branch → hook fires before throw → cause preserved through session log.

Fixture 3 — Plugin throw in turn-starting routes to error path

Setup: a MockAdapter with zero responses. A listener on agent/turn-starting throws new Error('plugin refuses to start turn'). A listener on agent/error records errors. Send a message, wait for idle.

Asserts:

• Adapter received zero model requests (turn didn't reach step).
• Final turn/end event has reason.kind === 'error'.
• agent/error fired exactly once.

Proves: the "veto turn start" capability plugins actually have — throw from the listener — produces a clean error path with full session log + error event, instead of silently dropping the turn.

Fixture 4 — Plugin throw in turn-aborting is caught and re-emitted as agent/error

Setup: same 'hang' adapter + 30 ms status guard as Fixture 2. A listener on agent/turn-aborting throws a sentinel error after recording the cause. A listener on agent/error captures the captured error.

Asserts:

• Listener was called with cause === { kind: 'user' } before throwing.
• Exactly one agent/error event was emitted, carrying the sentinel error (proves the catch in emitTurnAborting re-routes the throw).
• Final turn/end event has reason.kind === 'aborted' (NOT error — proves the listener's throw did not corrupt the turn-end or replace the original abort cause).

Proves: path 2 of the error-handling guarantees — a misbehaving turn-aborting listener cannot mask the abort or downgrade the turn-end reason.

Open questions for the maintainers

1. Naming: agent/turn-starting vs agent/turn-begin / agent/turn-open — happy to follow whatever convention is preferred. The agent/... prefix mirrors agent/pre-step and agent/turn-stopping.

2. Payload for turn-aborting: should cause be the raw signal.reason (typed as AgentCancelCause) or wrapped in { kind, ... }? Currently proposed as the raw AgentCancelCause value, matching how the agent's own cancel() method accepts it.

3. Documentation entry: docs/architecture.md is the proposed home. If there's a more specific "agent-loop events" catalog file, that's where it should land.

What this proposal does NOT include

• Plugin-initiated abort from inside these hooks (deferred — needs a separate agent/turn-cancel-request waterfall if ever).
• Turn-level telemetry emission (separate proposal if needed).
• Refactoring of the existing turnEnds! non-null assertion or step/turn-end finally block (orthogonal, not touched).

Working fork

A reference implementation lives on the branch feat/agent-turn-starting-aborting-hooks of the fork liuyang0508/deepseek-harness. Five functional commits land the proposal end-to-end (plus a marker commit 9864594 that bootstraps the branch from master):

Commit	Subject
ad09941	feat(agent): declare agent/turn-starting and agent/turn-aborting events
0231384	chore(gen): regenerate scoped-events and cordis catalog
90bded1	test(agent-loop): cover agent/turn-starting and agent/turn-aborting hooks
2954b4f	feat(agent-loop): fire agent/turn-starting and agent/turn-aborting hooks
3d35452	test(agent-loop): cover turn-aborting listener throw → agent/error route

Diff against master: compare view (10 files changed).

Local checks on the branch:

• pnpm exec vitest run packages/core/agent-loop — 333 tests pass, including 4 new fixtures (fires agent/turn-starting exactly once per turn in a natural completion, fires agent/turn-aborting with the abort cause before rethrow, records a turn-end with reason=error when a turn-starting listener throws, routes a turn-aborting listener throw through agent/error without corrupting turn-end).
• pnpm typecheck — exit 0
• pnpm lint — exit 0
• pnpm run gen-doc-graphs verify-doc-graphs — exit 0 (declare-and-dispatch atomicity preserved)
• pnpm exec vitest run packages/core/agent-loop --coverage --coverage.include='packages/core/agent-loop/src/**/*.{ts,tsx}' — agent.ts line coverage 100%, function coverage 100% for the new helpers. (The remaining uncovered line at agent.ts:143 is in runMaintenance, pre-existing code not touched by this change.)