refactor agent pre-step inbox lifecycle

packages/session-persistence/session-checkpoint-policy/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/session-persistence/session-checkpoint-policy/README.md
-README.md: aba0f00a2960eca3db06dda267cc954f602c1b09
-README.zh.md: ae403302f86b9fadc964c7963d3a454dd14180d3
+README.md: 57be9e78236775c39971c925f4972398c0b20a97
+README.zh.md: 66508382783c36c41be65afc758398d406c3a58f

packages/session-persistence/session-checkpoint-policy/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Semantic durability policy for persisted agents. It checkpoints the event-sourced session before a model adapter receives a request, before a top-level tool body may produce an external side effect, and at each `agent/step` boundary so the preceding response and ordered tool results are durable before the next request.
+Semantic durability policy for persisted agents. It checkpoints the event-sourced session before a model adapter receives a request, before a top-level tool body may produce an external side effect, and at each `agent/pre-step` boundary so the preceding response and ordered tool results are durable before the next request.
 
 ## Plugin (namespace: `session-checkpoint-policy`)
 
@@ -18,7 +18,7 @@ This zero-config function plugin consumes `ctx.sessions`, `ctx.llm`, `ctx.tools`
 
 Persistence and checkpoint scheduling are intentionally separate Cordis plugins. A persistence backend eagerly writes `session/event` appends and makes each requested `session/flush` an observation barrier; this policy chooses the request, tool-dispatch, and next-step barriers. Loading a backend without this policy is valid, but a crash may lose the latest eagerly buffered events. First-party persisted apps and runtimes mount both plugins explicitly; a specialized deployment may deliberately omit or replace the policy.
 
-The policy wraps `llm/stream` lazily, so the downstream stream is not constructed until the live session's buffered request events are durable. It wraps `tools/execute` after pre-execute policy and guards; a top-level tool body runs only after its recorded call is durable. If cancellation lands while that flush is pending, the wrapper returns the canonical `ABORTED_BEFORE_DISPATCH` result without entering the tool body. Nested tool dispatches reuse the outer model-visible call's checkpoint. `agent/step` persists the preceding response/result batch before request derivation.
+The policy wraps `llm/stream` lazily, so the downstream stream is not constructed until the live session's buffered request events are durable. It wraps `tools/execute` after pre-execute policy and guards; a top-level tool body runs only after its recorded call is durable. If cancellation lands while that flush is pending, the wrapper returns the canonical `ABORTED_BEFORE_DISPATCH` result without entering the tool body. Nested tool dispatches reuse the outer model-visible call's checkpoint. `agent/pre-step` persists the preceding response/result batch before request derivation.
 
 Checkpoint rejection is fail-closed at the model and tool boundaries: neither the adapter nor the top-level tool body runs. A step-boundary rejection fails the turn before another request starts. Concurrent tool checkpoints share the session store's serialized persistence drain and cannot duplicate sequence numbers.
 

packages/session-persistence/session-checkpoint-policy/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-已持久化的 agent（智能体）的语义持久性策略。它会在模型适配器收到请求前、顶层工具正文可产生外部副作用前，以及每个 `agent/step` 边界为事件溯源会话创建检查点，使前一响应与有序工具结果在下一个请求前已持久化。
+已持久化的 agent（智能体）的语义持久性策略。它会在模型适配器收到请求前、顶层工具正文可产生外部副作用前，以及每个 `agent/pre-step` 边界为事件溯源会话创建检查点，使前一响应与有序工具结果在下一个请求前已持久化。
 
 ## 插件（命名空间：`session-checkpoint-policy`）
 
@@ -18,7 +18,7 @@
 
 持久化与检查点调度刻意拆分为独立 Cordis 插件。持久化后端会主动写入追加的 `session/event`，并把每个已请求 `session/flush` 变成观测屏障；该策略选择请求、工具分派和下一步骤屏障。不带此策略加载后端是有效的，但崩溃可能丢失最新的已缓冲事件。第一方持久化应用和运行时显式挂载两个插件；专用部署可以刻意省略或替换策略。
 
-策略延迟包装 `llm/stream`，因此下游流只会在活动会话中缓冲的请求事件已持久化后构造。它在预执行策略和防护机制之后包装 `tools/execute`；只有在已记录调用已持久化后，顶层工具正文才会运行。如果取消在 flush 等待期间到达，包装层会返回规范的 `ABORTED_BEFORE_DISPATCH` 结果，不进入工具正文。嵌套工具分派重用外层模型可见调用的检查点。`agent/step` 在派生请求前持久化前一响应/结果批次。
+策略延迟包装 `llm/stream`，因此下游流只会在活动会话中缓冲的请求事件已持久化后构造。它在预执行策略和防护机制之后包装 `tools/execute`；只有在已记录调用已持久化后，顶层工具正文才会运行。如果取消在 flush 等待期间到达，包装层会返回规范的 `ABORTED_BEFORE_DISPATCH` 结果，不进入工具正文。嵌套工具分派重用外层模型可见调用的检查点。`agent/pre-step` 在派生请求前持久化前一响应/结果批次。
 
 在模型和工具边界，检查点被拒绝时会按失败即阻止原则处理：适配器和顶层工具正文都不运行。步骤边界处的检查点被拒绝会在另一个请求开始前使轮次失败。并发工具检查点共享会话存储的串行持久化排空流程，不会产生重复的序列号。
 

packages/session-persistence/session-checkpoint-policy/src/index.ts

@@ -8,7 +8,7 @@ import type { Context } from 'cordis'
 import type { Session } from '@deepseek-ai/dsh-session'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-agent'
+import type { PreStepDecision } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-session-persistence'
 
 /** Cordis plugin name used by Loader diagnostics. */
@@ -76,5 +76,8 @@ export function apply(ctx: Context): void {
 
   // Before each request, persist everything committed by the preceding step;
   // the first step's call is an intentional no-op beyond any prompt intake.
-  ctx.on('agent/step', (agent): Promise<void> => ctx.sessions.flush(agent.session))
+  ctx.on('agent/pre-step', async (agent, _messages, _context, next): Promise<PreStepDecision> => {
+    await ctx.sessions.flush(agent.session)
+    return next()
+  })
 }

packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts

@@ -220,13 +220,17 @@ describe('session-checkpoint-policy tool and step boundaries', () => {
     expect(flushes).toBe(0)
   })
 
-  it('checkpoints before the next agent step', async () => {
+  it('checkpoints during pre-step processing', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('post-step'))
     const agent = { session } as Agent
     const flushed: string[] = []
     ctx.on('session/flush', (current) => { flushed.push(current.id) })
-    await agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal)
+    const signal = new AbortController().signal
+    await agentEvents(ctx, agent).waterfall(
+      'agent/pre-step', [], { turn: 1, step: 1, signal },
+      () => Promise.resolve({ kind: 'enter', messages: [] }),
+    )
     expect(flushed).toEqual([session.id])
   })
 })