refactor(agent-loop): simplify message machine

packages/core/agent/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent/README.md
-README.md: 9ca79f28506b133a555bd7d1e984386c715fd9d6
-README.zh.md: 165f71f1b395bdf0c229e2c4b1a30e89347b6be1
+README.md: 2d373487b7ae17a68edfaa4c45d8479f869276a5
+README.zh.md: 9e3b043baa4832721c66d6d0752c8601ea9d817c

packages/core/agent/README.md

@@ -50,7 +50,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age
 
 The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
-Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives the exact error, normalized failure facts, and signal after the failed step closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery; the loop closes the failed turn and opens one numbered retry turn. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
+Most interception points are cooperative waterfalls. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. `agent/step` is the serial checkpoint before request derivation, while `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery; the loop closes the failed turn and opens one numbered retry turn. `agent/turn-stopping` runs before an otherwise completed turn closes. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
 
 `PromptDecision.additionalContexts` is an array of identified, frozen `UserMessage` values so every context keeps its own identity and source. The admitted prompt and every additional context become separate model-facing `user/message` events before the turn runs. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; replacing admitted content preserves the prompt's identity.
 
@@ -60,11 +60,10 @@ Turn and step boundaries and the model token stream are durable `session/event`
 
 The handle every plugin programs against:
 
-- `agent.send(message, options)` — the one delivery primitive over the (`target` × `wakeup`) matrix. `message` is an already identified, frozen `UserMessage`; callers normally create it with `createUserMessage()` before routing begins. `SendOptions` owns only the `target` and `wakeup` policy. The agent publishes or queues the complete value as-is without minting or replacing its identity. The message's `agent/inbox/enqueue`/`dequeue`/`discard` events carry it so callers can correlate a queued item with its lifecycle; enqueue and dequeue also carry the resolved `queued | steering` placement so repeated message identities retire from the correct FIFO. `target: 'next-turn'` queues one independent FIFO item that, if admitted, becomes the sole ordinary prompt in its turn. `target: 'next-step'` with `wakeup: true` submits steering, while `target: 'next-step'` with `wakeup: false` injects durable context without running the model. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
-- `agent.followup(input)` — the `next-turn`/wakeup preset of `send()`: queue an ordinary follow-up turn and wake the driver.
+- `agent.followup(input)` — queue an ordinary follow-up turn and wake the driver. Each admitted item becomes the sole ordinary prompt in its turn; the [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
 - `agent.steer(input)` — the `next-step`/wakeup preset: during prompt admission or an open turn, stage steering for the next safe boundary without dispatching `agent/prompt-submit`; outside that acceptance window, delegate to a woken follow-up. Admission failure leaves staged steering for retry or a later admitted prompt, while cancellation or disposal may discard it.
 - `agent.inject(input)` — the `next-step`/no-wakeup preset: append model-facing context without running the model; the next request sees a verbatim user-role message whose provenance is carried by the required `input.source`. During prompt admission or an open turn, injection waits in the outbox for the next safe boundary. Outside that acceptance window, it appends immediately without opening a turn; a context-only admission batch takes this fallback if admission closes without a turn, while context staged beside steering remains pending with it. Persistence reacts to `session/event` independently. Injection emits no `agent/inbox/*` event.
-- `agent.acceptsNextStep` — whether a `next-step` send would currently join prompt admission or the open turn. Use this narrower routing predicate when a caller must choose between steering and a fresh admitted prompt; `status === 'running'` also covers admission exit and turn settlement.
+- `agent.acceptsNextStep` — whether steering would currently join prompt admission or the open turn. Use this narrower routing predicate when a caller must choose between steering and a fresh admitted prompt; `status === 'running'` also covers admission exit and turn settlement.
 - `agent.cancel(cause, options?)` — cancel the active turn and, unless `options.keepInbox`, ALL pending work. Callers must choose the `user | parent` cause explicitly; an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; dropped items are reported on `agent/inbox/discard`, and observers may synchronize state but cannot veto cancellation. `keepInbox: true` aborts the turn but preserves queued and steering items (no discard, and un-started work is not dropped). The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`

packages/core/agent/README.zh.md

@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器静默后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
 
-大多数拦截点都是协作式 waterfall。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：失败步骤关闭后，它接收确切错误、规范化失败事实和信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall。轮次作用域的异步 seam 接收一个显式 `AbortSignal`，其中 `signal` 紧邻 waterfall 最终的 `next`；监听器可以配合，但不得将它保留为控制另一轮次的权限。`agent/step` 是派生请求前的串行检查点，而 `agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时的服务注册重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`；循环会关闭失败轮次，并打开一个编号重试轮次。`agent/turn-stopping` 在本可完成的轮次关闭前运行。普通排队提示词保持原样。有效的广义取消会先发出只观测的 `agent/cancel-requested` 及其解析后的类型化原因，再清空队列并中止；通知失败会被收容，不能 veto 停止。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
 `PromptDecision.additionalContexts` 是由带标识且冻结的 `UserMessage` 值组成的数组，因此每个上下文都保留自己的标识和来源。获准的提示词与每个附加上下文都会在轮次运行前成为各自独立、面向模型的 `user/message` 事件。包装下游允许决策的监听器会保留其 `content` 与 `additionalContexts`，除非有意替换任一字段；替换获准内容时仍会保留提示词的标识。
 
@@ -60,11 +60,10 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 每个插件面向的 handle：
 
-- `agent.send(message, options)`：覆盖（`target` × `wakeup`）矩阵的唯一投递原语。`message` 是已有标识且已冻结的 `UserMessage`；调用方通常会在开始路由前使用 `createUserMessage()` 创建它。`SendOptions` 只持有 `target` 与 `wakeup` 策略。agent 会原样发布或排队完整值，不会生成或替换其标识。该消息的 `agent/inbox/enqueue`/`dequeue`/`discard` 事件会携带完整消息，调用方可据此把排队项与其生命周期关联；入队与出队事件还会携带解析出的 `queued | steering` 路由归类，使重复出现的消息标识能在正确的 FIFO 中完成结算。`target: 'next-turn'` 排队一条独立 FIFO 项，获准后成为其轮次中唯一的普通提示词。`target: 'next-step'` 且 `wakeup: true` 提交 steering（中途引导），而 `target: 'next-step'` 且 `wakeup: false` 注入持久上下文，不运行模型。轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。
-- `agent.followup(input)`：`send()` 的 `next-turn`／wakeup 预设：排队一个普通后续轮次并唤醒驱动器。
+- `agent.followup(input)`：排队一个普通后续轮次并唤醒驱动器。每个获准项都会成为其轮次中唯一的普通提示词；轮次原理由 [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)拥有。
 - `agent.steer(input)`：`next-step`／wakeup 预设：提示词接纳期间或轮次打开时，为下一个安全边界暂存 steering，且不分发 `agent/prompt-submit`；该接收窗口之外则委托给会唤醒的后续轮次。接纳失败会保留暂存的 steering，以供重试或之后获准的提示词使用，而取消或 dispose 可能丢弃它。
 - `agent.inject(input)`：`next-step`／不唤醒预设：追加面向模型的上下文而不运行模型；下一次请求会看到一条逐字的 user role 消息，其来源由必填的 `input.source` 携带。提示词接纳期间或轮次打开时，注入会在 outbox 中等待下一个安全边界。该接收窗口之外，它会立即追加而不开启轮次；如果接纳结束却未开启轮次，仅含上下文的接纳批次会采用这一回退，而与 steering 一同暂存的上下文则会随其继续待处理。持久化独立地响应 `session/event`。注入不发出 `agent/inbox/*` 事件。
-- `agent.acceptsNextStep`：当前发送 `next-step` 时，是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。
+- `agent.acceptsNextStep`：steering 当前是否会加入提示词接纳或已打开的轮次。当调用方必须在 steering 与新接纳的提示词之间选择时，应使用这一更窄的路由判定；`status === 'running'` 还涵盖接纳收尾与轮次结算阶段。
 - `agent.cancel(cause, options?)`：取消活动轮次，并在未设置 `options.keepInbox` 时取消全部待处理工作。调用方必须显式选择 `user | parent` 原因；活动持有者会在中止前把其判别字段复制为已分离、冻结的信号原因。有效调用会在清除排队与 steering 工作前，随原因发出 `agent/cancel-requested`；丢弃项在 `agent/inbox/discard` 上报告，观察方可以同步状态，但不能 veto 取消。`keepInbox: true` 会中止轮次，但保留排队与 steering 项（不丢弃，且不删除尚未开始的工作）。同进程类型化 seam 不会为无类型调用方添加运行时校验或兼容回退。重复取消活动轮次时，首个信号生效；空闲取消是安全空操作，不发通知。ACP 映射到 `user`，进程内父传播映射到 `parent`。原因只存在于运行时；持久 `turn/end` 保持粗粒度的 `aborted`。
 - `agent.whenIdle()`：agent 从 `running` 结算后达到静默时解析（idle ⇒ 立即；disposed ⇒ 等待循环退出）。这是非拥有者的静默观测钩子：观察工作结算，但不 teardown agent。Teardown 独立存在；生命周期拥有者通过 `AgentHandle.dispose()` 停止并注销，并直接等待循环退出。
 - `agent.session`、`agent.status`、`agent.options`、`agent.id`

packages/core/agent/src/invariant.ts

@@ -21,27 +21,6 @@ const install: InvariantInstaller = (ctx, fail) => {
     }
     lastStatus.set(agent, status)
   }, { global: true })
-
-  // Inbox FIFO conservation: an item leaves the inbox (dequeue) or is dropped
-  // (discard) only after it entered (enqueue), so the live outstanding count
-  // per agent can never go negative. Injection bypasses the FIFOs entirely and
-  // never appears on these events.
-  const outstanding = new WeakMap<Agent, number>()
-  ctx.on('agent/inbox/enqueue', (agent) => {
-    outstanding.set(agent, (outstanding.get(agent) ?? 0) + 1)
-  }, { global: true })
-  ctx.on('agent/inbox/dequeue', (agent) => {
-    const count = outstanding.get(agent) ?? 0
-    if (count <= 0) fail('agent/inbox/dequeue without a matching prior enqueue')
-    outstanding.set(agent, count - 1)
-  }, { global: true })
-  ctx.on('agent/inbox/discard', (agent, items) => {
-    const count = outstanding.get(agent) ?? 0
-    if (items.length > count) {
-      fail(`agent/inbox/discard dropped ${items.length} items but only ${count} were outstanding`)
-    }
-    outstanding.set(agent, count - items.length)
-  }, { global: true })
 }
 
 /**

packages/core/agent/src/types.ts

@@ -7,8 +7,9 @@
 
 import type { Context } from 'cordis'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type { ContentBlock, LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
+import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
+import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
+export type { AgentCancelCause } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -27,95 +28,55 @@ export interface AgentOptions {
   maxTokens?: number
 }
 
-/**
- * Which inbox queue a {@link Agent.send} item joins:
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
- * - `next-step` — during prompt admission or an open turn, the item stages for
- *   the next safe step boundary; otherwise it is promoted per its `wakeup`
- *   flag.
- */
-export type SendTarget = 'next-turn' | 'next-step'
-
-/** Resolved inbox placement reported when an accepted message is enqueued. */
-export type InboxPlacement = 'queued' | 'steering'
-
-/**
- * Options for the unified {@link Agent.send} primitive over the
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
- * {@link Agent.inject} (`next-step`/no-wakeup).
- *
- * The object is complete so routing policy is explicit.
- */
-export interface SendOptions {
-  /** Queue the item joins. */
-  target: SendTarget
-  /**
-   * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). A `false`
-   * `next-turn` item queues without waking; a `false`
-   * `next-step` item attaches durable context without forcing another step
-   * (the injection preset).
-   */
-  wakeup: boolean
-}
-
 /** Options for {@link Agent.cancel}. */
 export interface CancelOptions {
   /**
    * Preserve queued and steering inbox items instead of discarding them. The
    * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no `agent/inbox/discard` fires.
+   * later turn and no `agent/inbox/canceled` fires.
    */
-  keepInbox?: boolean
+  keepInbox?: boolean | undefined
 }
 
 /**
  * An agent's lifecycle state, emitted on every transition as `agent/status`:
- * `idle` (parked, waiting for queued work), `running` (the driver is draining
- * work and may be closing or checkpointing a turn). Disposal removes the
- * agent from its registry; it is not a third observable status.
+ * `idle` means no driver is scheduled or active; `running` begins when a
+ * cancellable admission is scheduled and lasts while the driver drains,
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
+ * it is not a third observable status.
  */
 export type AgentStatus = 'idle' | 'running'
 
 /**
- * Prompt interception result. `allow.content` replaces the prompt, while
- * `additionalContexts` appends model-facing context before the turn starts.
- * An `allow` returned by a listener is authoritative: a listener wrapping
- * `next()` preserves both fields unless it intentionally replaces them.
+ * Prompt interception result. An allowed batch replaces the submitted
+ * messages. A listener wrapping `next()` preserves the returned batch unless
+ * it intentionally replaces it.
  */
 export type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
-  | { kind: 'block'; reason: string }
+  | { kind: 'allow'; messages: UserMessage[] }
+  | { kind: 'block'; reason: string; keepInbox?: boolean }
 
-/** Model-request failure with an optional machine-routable provider code. */
-export type RequestError = Error & { code?: string }
+/** One failed model-request attempt presented to recovery listeners. */
+export interface RequestFailureContext {
+  /** Turn containing the failed request. */
+  readonly turn: number
+  /** Step containing the failed request attempt. */
+  readonly step: number
+  /** Provider selected for the failed request. */
+  readonly provider: string
+  /** Serializable facts normalized at the final adapter boundary. */
+  readonly failure: LlmFailure
+  /** Policy of the adapter registration that served the failed request. */
+  readonly retryPolicy: ResolvedRetryPolicy | undefined
+}
 
 /** Action returned by a listener that owns model-request recovery. */
 export type RequestErrorAction = { kind: 'retry' } | undefined
 
-/**
- * Why a turn ended, reported live on `agent/settled` right after the turn's
- * durable `turn/end`. `error` carries the thrown value verbatim for observers;
- * model-request recovery runs earlier through `agent/request-error`.
- */
-export type SettleReason =
-  | { kind: 'completed' }
-  | { kind: 'aborted' }
-  | { kind: 'error'; error: unknown; failure?: LlmFailure }
-
 /** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
 export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
-export type AgentCancelCause =
-  | { readonly kind: 'user' }
-  | { readonly kind: 'parent' }
-
-/** Runtime reason carried by the signal that controls one live turn. */
-export type AgentInterruptReason = AgentCancelCause | { readonly kind: 'disposed' }
-
-/** Public live-agent handle with aliases over the unified delivery primitive. */
+/** Public live-agent handle. */
 export interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -125,77 +86,46 @@ export interface Agent {
   readonly session: Session
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
-  /**
-   * Whether a `next-step` send currently stages for prompt admission or the
-   * open turn. Unlike {@link status}, this excludes admission exit and turn
-   * settlement, when a waking `next-step` send becomes a queued follow-up.
-   */
-  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
-  /**
-   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
-   * It routes the caller's typed content and source as follows:
-   *
-   * - `next-turn` queues an item that becomes the sole ordinary message of its
-   *   own FIFO-ordered turn; `wakeup:true` wakes a
-   *   parked driver, while `wakeup:false` queues without waking.
-   * - `next-step` with `wakeup:true` stages steering during prompt admission
-   *   or an open turn; outside that window it falls back to a woken
-   *   `next-turn`.
-   * - `next-step` with `wakeup:false` injects durable model-facing context
-   *   without running the model: admission or an open turn stages it for the
-   *   next safe log position, while an injection outside that window appends
-   *   immediately without opening a turn. If admission closes without a turn,
-   *   a context-only boundary appends immediately; context staged beside
-   *   steering remains pending with it.
-   * The agent publishes or queues the identified frozen message as-is.
-   * @param message - identified model-facing content and its producer provenance.
-   * @param options - target queue and wakeup decision.
-   */
-  send(message: UserMessage, options: SendOptions): void
-
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn. An effective call first emits `agent/cancel-requested` with the
-   * resolved typed cause. The first cause wins for the active turn, and
-   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
-   * cancellation is a no-op and does not arm later work.
+   * turn. The first cause wins for the active turn. Idle cancellation is a
+   * no-op and does not arm later work.
    * @param cause - the stable caller intent carried by the current turn signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
+  /**
+   * Resolve after the current whole-agent activity reaches quiescence. This
+   * follows replacement work scheduled before the observed driver retires,
+   * but does not identify the settlement of any particular message.
+   * @returns fulfillment after no scheduled or active driver remains.
+   */
   whenIdle(): Promise<void>
 
   /**
-   * Queue an ordinary follow-up turn and wake the driver — the
-   * `next-turn`/wakeup preset of {@link send}. The item becomes the sole
-   * ordinary message of its own turn.
+   * Queue an ordinary follow-up turn and wake the driver. The item becomes the
+   * sole ordinary message of its own turn.
    * @param message - identified prompt content and its producer provenance.
    */
   followup(message: UserMessage): void
 
   /**
-   * Submit steering during prompt admission or an open turn — the
-   * `next-step`/wakeup preset of {@link send}. It stages for the next steering
-   * checkpoint before a request or stop decision. If the activity fails before
-   * that boundary, the remainder stays staged without waking the agent; retry
-   * or a later prompt takes it. Outside that window steering falls back to a
-   * woken follow-up turn, while cancellation or disposal may discard pending
-   * steering.
+   * Submit steering for the nearest step. An idle driver schedules a turn;
+   * collecting and running drivers consume it at their next step boundary.
+   * Cancellation or disposal may discard pending steering.
    * @param message - identified steering content and its producer provenance.
    */
   steer(message: UserMessage): void
 
   /**
-   * Append model-facing context without running the model — the
-   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
-   * stages it at the next safe log position; outside that window it appends
-   * immediately without opening a turn. If admission closes without a turn,
-   * a context-only boundary appends immediately; context staged beside
+   * Append model-facing context without running the model. Admission or an
+   * open turn stages it at the next safe log position; outside that window it
+   * appends immediately without opening a turn. If admission closes without a
+   * turn, a context-only boundary appends immediately; context staged beside
    * steering remains pending with it.
    * @param message - identified injected context and its producer provenance.
    */
@@ -226,8 +156,9 @@ declare module 'cordis' {
      */
     'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
-     * `running` synchronously; drive lifecycle from this event.
+     * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+     * `running` synchronously after reserving cancellation; `idle` means no
+     * driver remains scheduled or active.
      * @param agent - the agent whose status flipped.
      * @param status - the status just entered (the transition's destination).
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
@@ -235,56 +166,23 @@ declare module 'cordis' {
      */
     'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
     /**
-     * An item entered the queued or steering inbox. `placement` is the
-     * acceptance-time routing result; listeners must not reconstruct it from
-     * later agent or session state.
-     * @param agent - the owning agent.
-     * @param message - accepted content, source, and correlation identity.
-     * @param placement - resolved queued or steering placement.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-     * @mode emit
-     */
-    'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, message: UserMessage, placement: InboxPlacement): void
-    /**
-     * The driver claimed one item out of the inbox: a queued item at a turn
-     * boundary, or steering drained between steps. Fires after the item leaves
-     * its FIFO and before it becomes a durable message.
+     * The driver admitted one inbox item for model-visible history.
      * @param agent - the agent whose inbox item was claimed.
-     * @param message - the claimed message.
-     * @param placement - the FIFO that claimed this occurrence; together with
-     *   `message.id`, it matches the earliest outstanding enqueue in that FIFO.
+     * @param message - the admitted message.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/dequeue'(
-      this: Scoped<Agent>,
-      agent: Agent,
-      message: UserMessage,
-      placement: InboxPlacement,
-    ): void
+    'agent/inbox/admitted'(this: Scoped<Agent>, agent: Agent, message: UserMessage): void
     /**
-     * Pending inbox items were dropped without delivering them, so every
-     * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
-     * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
-     * emits this after `agent/cancel-requested` when applicable and before
-     * aborting the active work. Fires once per drop with every dropped item.
+     * One pending inbox item was dropped without entering model-visible
+     * history. `cancel()` without `keepInbox`, including disposal, emits this
+     * once for each dropped item before aborting active work.
      * @param agent - the agent whose inbox items were dropped.
-     * @param messages - the discarded messages in FIFO order (queued then steering); never empty.
+     * @param message - the dropped message.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, messages: UserMessage[]): void
-    /**
-     * Effective broad cancellation was requested, before queued/outbox work
-     * is cleared or the active turn is aborted. This observe-only notification
-     * cannot veto cancellation; listener failures are contained.
-     * @param agent - the agent whose current work is being cancelled.
-     * @param cause - the explicit typed cancellation cause.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-     * @mode emit
-     */
-    'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
-
+    'agent/inbox/canceled'(this: Scoped<Agent>, agent: Agent, message: UserMessage): void
     // ---- session lifecycle (emit) ----
     /**
      * The session lifecycle began, once before the first turn. Use
@@ -300,17 +198,17 @@ declare module 'cordis' {
 
     // ---- the machine's extension seams ----
     /**
-     * Allow, rewrite, or block one claimed prompt before it becomes a user
-     * message or opens a turn. Call `next()` for the unchanged default. The
+     * Allow, rewrite, or block one claimed inbox batch before it becomes
+     * model-visible or opens a turn. Call `next()` for the unchanged default. The
      * signal controls only this admission attempt; listeners may cooperate with
      * it but must not retain it for a later attempt or turn.
-     * @param agent - the agent whose turn claimed the message.
-     * @param message - the frozen claimed message, including identity and source.
+     * @param agent - the agent whose driver claimed the batch.
+     * @param messages - the claimed messages.
      * @param signal - the current turn's explicit abort signal.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
-    'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
+    'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, messages: UserMessage[], signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
     /**
      * Awaited serial checkpoint before EVERY request of a turn is built (the
      * first as well as each post-tools continuation). The single "between
@@ -338,24 +236,17 @@ declare module 'cordis' {
     */
     'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
     /**
-     * Handle a model-request failure after its failed step has closed but
-     * before the failed turn closes. A listener returns `{ kind: 'retry' }`
-     * without calling `next()` when it owns the error, or calls `next()` to
-     * delegate. The default `undefined` leaves the failure terminal.
+     * Handle one failed model-request attempt before the loop retries or closes
+     * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+     * when it owns recovery, or calls `next()` to delegate. The default
+     * `undefined` leaves the failure terminal.
      * @param agent - the agent whose request failed.
-     * @param turn - the open turn number.
-     * @param step - the failed step number.
-     * @param error - the original model-request failure.
-     * @param failure - serializable facts normalized at the final adapter boundary.
-     * @param priorFailures - immutable failures that already authorized another
-     * retry turn in this consecutive sequence.
-     * @param retryPolicy - immutable policy of the adapter registration that served
-     * the failed request, or `undefined` if no final adapter served it.
+     * @param context - request coordinates, provider, normalized failure, and serving policy.
      * @param signal - the turn abort signal.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
-    'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+    'agent/request-error'(this: Scoped<Agent>, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
     /**
      * The turn is about to close: the model owes no response (no live tool
      * calls, no fresh steering). Awaited before the boundary commits — a
@@ -371,21 +262,6 @@ declare module 'cordis' {
      * @mode serial
      */
     'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
-    /**
-     * One drain chain reached its terminal turn: that turn's `turn/end` is
-     * already committed. Automatically recovered failed turns do not emit this
-     * notification, and neither does a run that aborts or fails before its
-     * `turn/start` commits — there is no durable turn to settle against.
-     * `reason` says why; model-request recovery is exhausted when an error
-     * reaches it.
-     * @param agent - the agent whose turn closed.
-     * @param turn - the terminal turn number.
-     * @param reason - why the terminal turn ended, with live error facts when it failed.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-     * @mode emit
-     */
-    'agent/settled'(this: Scoped<Agent>, agent: Agent, turn: number, reason: SettleReason): void
-
     // ---- error notifications (emit) ----
     /**
      * A step or turn errored. The machine reports a failure here (plus the
@@ -400,3 +276,10 @@ declare module 'cordis' {
     'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
   }
 }
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /** One message was accepted into the agent inbox. */
+    'agent/inbox/added': UserMessage
+  }
+}

packages/core/agent/tests/agent.spec.ts

@@ -1,6 +1,5 @@
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context, Service, symbols } from 'cordis'
-import type { Events } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, {
   agentEvents,
@@ -21,14 +20,11 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
     options: {},
     session: new Session(id),
     status: 'idle',
-    acceptsNextStep: false,
     ctx: new Context(),
-    send: () => {},
     followup: () => {},
     steer: () => {},
     inject: () => {},
     cancel() {},
-    whenIdle() { return Promise.resolve() },
   }
   return Object.assign(agent, overrides)
 }
@@ -188,7 +184,6 @@ describe('agentEvents()', () => {
 describe('explicit cancellation contract', () => {
   it('exposes the closed typed cancellation cause at the Agent seam', () => {
     expectTypeOf<Parameters<Agent['cancel']>[0]>().toEqualTypeOf<AgentCancelCause>()
-    expectTypeOf<Parameters<Events['agent/cancel-requested']>[1]>().toEqualTypeOf<AgentCancelCause>()
   })
 })
 

packages/core/agent/tsdown.config.ts

@@ -1,6 +1,6 @@
 import { defineConfig } from 'tsdown'
 
-/** Build the package root and optional invariant companion as independent bundles. */
+/** Build the package root and companions as independent bundles. */
 export default defineConfig([
   {
     entry: ['lib/types/index.js'],