refactor: identify and freeze messages at creation

2026-08-15 21:04:50 +00:00 · 2026-07-28 13:55:59 +08:00
parent c49c0ba497
commit fbf87e660c
345 changed files with 5220 additions and 2901 deletions
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: 357712bd197ac2e0661e6bc61a638aa8a4738356
-core.zh.md: dcb7210d37377da99ac2cd68b1ce18fa6e90e0b8
+core.md: 140e799aa159f54ffb2805e9756f914a86cb80cb
+core.zh.md: daf193835a7b2781eb98d6c971bb477646598701
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -116,7 +116,9 @@ interface ContentBlockMap {

 The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the merge-extensible map together with the adapter/UI/compaction support that honors it.

-A `Message` is a role plus blocks. Loop-derived assistant messages carry their durable provider/model identity and optional adapter-private replay metadata:
+Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:

 ```ts type-equiv
 /** Provider ownership and adapter-private replay data for an assistant message. */
@@ -135,15 +137,16 @@ interface AssistantProvenance {
 ```

 ```ts type-equiv
-/**
- * A single message in a conversation history. Loop-derived assistant messages
- * always carry provenance; callers may omit it on hand-built foreign history.
- */
+/** One immutable message representation shared by delivery, durable history, and model requests. */
 interface Message {
-  role: 'system' | 'user' | 'assistant'
-  content: ContentBlock[]
-  /** Present only on assistant messages produced by a routed adapter. */
-  provenance?: AssistantProvenance
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
 }
 ```

@@ -157,6 +160,8 @@ Where a message came from is itself a merge-extensible sum type:
 interface MessageSourceMap {
  user: { kind: 'user' }
  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
 }
 ```

@@ -448,32 +453,7 @@ interface SendOptions {
 }
 ```

-The fixed-preset aliases own `target` and `wakeup`; their `UserMessageData` input carries both content and provenance.
-
-`send` returns the accepted message's opaque `AgentMessageId`, stable across that message's `agent/inbox/*` events:
-
-```ts type-equiv
-/**
- * Opaque id assigned to one accepted {@link Agent.send} message; returned by
- * `send` and carried on its `agent/inbox/*` events for correlation.
- */
-type AgentMessageId = Branded<'AgentMessageId'>
-```
-
-The `agent/inbox/*` live events carry one accepted message; injection bypasses the FIFOs and never appears on them:
-
-```ts type-equiv
-/**
- * One accepted {@link Agent.send} message, carried by the `agent/inbox/*` live
- * events. `id` is the value `send` returned to the caller, stable across this
- * message's enqueue, dequeue, and discard events. The agent snapshots and
- * freezes the accepted content and source before enqueue observers receive it.
- */
-interface AgentMessage extends UserMessageData {
-  /** The id `send` returned for this message. */
-  id: AgentMessageId
-}
-```
+The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable across that message's `agent/inbox/*` events without being returned by the delivery methods. Injection bypasses the FIFOs and never appears on those events.

 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -532,12 +512,11 @@ interface Agent {
   *   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 snapshots and freezes `input` before publishing or queueing it.
-   * @param input - model-facing content and its producer provenance.
+   * The agent snapshots and freezes the identified message before publishing or queueing it.
+   * @param message - identified model-facing content and its producer provenance.
   * @param options - target queue and wakeup decision.
-   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
   */
-  send(input: UserMessageData, options: SendOptions): AgentMessageId
+  send(message: UserMessage, options: SendOptions): void

  /**
   * Clear queued and steering work — unless `keepInbox` — and abort the active
@@ -557,10 +536,9 @@ interface Agent {
   * 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.
-   * @param input - prompt content and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified prompt content and its producer provenance.
   */
-  followup(input: UserMessageData): AgentMessageId
+  followup(message: UserMessage): void

  /**
   * Submit steering during prompt admission or an open turn — the
@@ -570,10 +548,9 @@ interface Agent {
   * 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.
-   * @param input - steering content and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified steering content and its producer provenance.
   */
-  steer(input: UserMessageData): AgentMessageId
+  steer(message: UserMessage): void

  /**
   * Append model-facing context without running the model — the
@@ -582,10 +559,9 @@ interface Agent {
   * 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 input - injected context and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified injected context and its producer provenance.
   */
-  inject(input: UserMessageData): AgentMessageId
+  inject(message: UserMessage): void
 }
 ```

@@ -601,7 +577,7 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,

 ## Interception decisions

-Prompt and post-tool decisions use the same `UserMessageData` content/source shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its provenance. Hook bridges map their native decision fields onto these typed results.
+Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.

 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)

@@ -615,7 +591,7 @@ Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types
 * `next()` preserves both fields unless it intentionally replaces them.
 */
 type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessageData[] }
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
  | { kind: 'block'; reason: string }
 ```

--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -122,7 +122,9 @@ interface ContentBlockMap {

 各块接口（完整字段见源码）：`TextBlock`（`text`）、`ReasoningBlock`（thinking，区别于可见文本）、`ToolCallBlock`（`id: CallId`、`name`、原始 JSON `arguments`）、`ToolResultBlock`（`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`）。`ContentBlock = ContentBlockMap[ContentBlockType]`。核心集仅限于每条交付路径都尊重的块——多模态内容（图像、音频等）没有核心块类型；需要的功能通过可合并扩展的 map 添加，同时提供适配器/UI/压缩支持。

-`Message` 由角色和块组成。由循环派生的 assistant 消息携带其持久提供方/模型标识，以及可选的适配器私有回放元数据：
+源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：

 ```ts type-equiv
 /** Provider ownership and adapter-private replay data for an assistant message. */
@@ -141,15 +143,16 @@ interface AssistantProvenance {
 ```

 ```ts type-equiv
-/**
- * A single message in a conversation history. Loop-derived assistant messages
- * always carry provenance; callers may omit it on hand-built foreign history.
- */
+/** One immutable message representation shared by delivery, durable history, and model requests. */
 interface Message {
-  role: 'system' | 'user' | 'assistant'
-  content: ContentBlock[]
-  /** Present only on assistant messages produced by a routed adapter. */
-  provenance?: AssistantProvenance
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
 }
 ```

@@ -163,6 +166,8 @@ interface Message {
 interface MessageSourceMap {
  user: { kind: 'user' }
  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
 }
 ```

@@ -456,32 +461,7 @@ interface SendOptions {
 }
 ```

-固定预设的别名方法自带 `target` 与 `wakeup`；其 `UserMessageData` 输入同时携带内容与 provenance。
-
-`send` 返回被接收消息的不透明 `AgentMessageId`，该 id 在这条消息的各个 `agent/inbox/*` 事件中保持稳定：
-
-```ts type-equiv
-/**
- * Opaque id assigned to one accepted {@link Agent.send} message; returned by
- * `send` and carried on its `agent/inbox/*` events for correlation.
- */
-type AgentMessageId = Branded<'AgentMessageId'>
-```
-
-`agent/inbox/*` 实时事件承载一条已接收的消息；注入绕过两个 FIFO，从不出现在这些事件中：
-
-```ts type-equiv
-/**
- * One accepted {@link Agent.send} message, carried by the `agent/inbox/*` live
- * events. `id` is the value `send` returned to the caller, stable across this
- * message's enqueue, dequeue, and discard events. The agent snapshots and
- * freezes the accepted content and source before enqueue observers receive it.
- */
-interface AgentMessage extends UserMessageData {
-  /** The id `send` returned for this message. */
-  id: AgentMessageId
-}
-```
+固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。投递方法不会返回其 `MessageId`，但该 id 在这条消息的各个 `agent/inbox/*` 事件中保持稳定。注入绕过两个 FIFO，从不出现在这些事件中。

 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -540,12 +520,11 @@ interface Agent {
   *   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 snapshots and freezes `input` before publishing or queueing it.
-   * @param input - model-facing content and its producer provenance.
+   * The agent snapshots and freezes the identified message before publishing or queueing it.
+   * @param message - identified model-facing content and its producer provenance.
   * @param options - target queue and wakeup decision.
-   * @returns the accepted message's {@link AgentMessageId}, stable across its `agent/inbox/*` events.
   */
-  send(input: UserMessageData, options: SendOptions): AgentMessageId
+  send(message: UserMessage, options: SendOptions): void

  /**
   * Clear queued and steering work — unless `keepInbox` — and abort the active
@@ -565,10 +544,9 @@ interface Agent {
   * 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.
-   * @param input - prompt content and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified prompt content and its producer provenance.
   */
-  followup(input: UserMessageData): AgentMessageId
+  followup(message: UserMessage): void

  /**
   * Submit steering during prompt admission or an open turn — the
@@ -578,10 +556,9 @@ interface Agent {
   * 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.
-   * @param input - steering content and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified steering content and its producer provenance.
   */
-  steer(input: UserMessageData): AgentMessageId
+  steer(message: UserMessage): void

  /**
   * Append model-facing context without running the model — the
@@ -590,10 +567,9 @@ interface Agent {
   * 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 input - injected context and its producer provenance.
-   * @returns the accepted message's {@link AgentMessageId}.
+   * @param message - identified injected context and its producer provenance.
   */
-  inject(input: UserMessageData): AgentMessageId
+  inject(message: UserMessage): void
 }
 ```

@@ -609,7 +585,7 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancella

 ## 拦截决策

-提示词决策与工具后决策使用与持久 user-role 输入相同的 `UserMessageData` content/source 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。
+提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。

 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)

@@ -623,7 +599,7 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancella
 * `next()` preserves both fields unless it intentionally replaces them.
 */
 type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessageData[] }
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
  | { kind: 'block'; reason: string }
 ```

--- a/docs/core-data-structures/llm-streaming.i18n.yaml
+++ b/docs/core-data-structures/llm-streaming.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 docs/core-data-structures/llm-streaming.md
-llm-streaming.md: db46deee28cd053d034f889eb7625c9f222b418b
-llm-streaming.zh.md: fbff50bf1f3b86afd313c2d5020c15dd88e0b449
+llm-streaming.md: 6811611768a0ec577360a8ff82792899cf3b8fec
+llm-streaming.zh.md: 35374af6a20086f15384840689dba5aa24351750
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -153,9 +153,10 @@ declare class BlockAssembler {
  get replayState(): unknown;
  /**
   * The assembled assistant message.
-   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   * @param source - producer attribution for the assembled message.
+   * @returns a frozen assistant-role message over `blocks()` (same open-block assembly rules).
   */
-  message(): Message;
+  message(source: MessageSource = { kind: 'plugin', plugin: 'dsh-llm/assembler' }): Message;
 }
 ```

--- a/docs/core-data-structures/llm-streaming.zh.md
+++ b/docs/core-data-structures/llm-streaming.zh.md
@@ -153,9 +153,10 @@ declare class BlockAssembler {
  get replayState(): unknown;
  /**
   * The assembled assistant message.
-   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   * @param source - producer attribution for the assembled message.
+   * @returns a frozen assistant-role message over `blocks()` (same open-block assembly rules).
   */
-  message(): Message;
+  message(source: MessageSource = { kind: 'plugin', plugin: 'dsh-llm/assembler' }): Message;
 }
 ```

--- a/docs/core-data-structures/session-reference.i18n.yaml
+++ b/docs/core-data-structures/session-reference.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-session-reference.md: a19df1702429be23ff6ef4f7062a68b8286c3644
-session-reference.zh.md: 4a8b7c2b9dcb02f130d551d4951a771328a842b9
+#   pnpm run verify-translation-pairing --write docs/core-data-structures/session-reference.md
+session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a
+session-reference.zh.md: 8e9abea7ce87e51061813d282e20db951918a650
--- a/docs/core-data-structures/session-reference.md
+++ b/docs/core-data-structures/session-reference.md
@@ -46,7 +46,7 @@ interface PreparedReferencedMessage {
  /** Readable message content after host mention tokens are removed. */
  content: ContentBlock[]
  /** Aggregated untrusted snapshot, absent when the message has no references. */
-  additionalContext?: UserMessageData
+  additionalContext?: UserMessage
 }
 ```

--- a/docs/core-data-structures/session-reference.zh.md
+++ b/docs/core-data-structures/session-reference.zh.md
@@ -46,7 +46,7 @@ interface PreparedReferencedMessage {
  /** Readable message content after host mention tokens are removed. */
  content: ContentBlock[]
  /** Aggregated untrusted snapshot, absent when the message has no references. */
-  additionalContext?: UserMessageData
+  additionalContext?: UserMessage
 }
 ```

--- a/docs/core-data-structures/session.i18n.yaml
+++ b/docs/core-data-structures/session.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 docs/core-data-structures/session.md
-session.md: 058236cb628f0e517fe18b0e4276dba46bd6b0b0
-session.zh.md: 2d8022c7892828a30094728a1449d16dddd2fd89
+session.md: 6ce26e2e76d35efb74141022288bf0455de690a7
+session.zh.md: 23f5d52333b93c4bf3fd25a7910e70e7a0795725
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -11,18 +11,9 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
 The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` provenance for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.

 ```ts type-equiv
-/**
- * Shared payload for user, injected-context, and steering messages. A
- * direct human prompt, a synthetic `agent.inject()` context, and mid-turn
- * steering all project into the model transcript as verbatim user-role content;
- * they are told apart by `source` (a non-`user` kind marks injected context),
- * not by event type.
- */
-interface UserMessageData {
-  /** Exact model-facing blocks. */
-  content: ContentBlock[]
-  /** Producer provenance. */
-  source: MessageSource
+/** A user-role specialization of the one shared message representation. */
+interface UserMessage extends Message {
+  readonly role: 'user'
 }
 ```

@@ -57,7 +48,7 @@ interface SessionEventMap {
   * project their `content` verbatim; `source` tells them apart. An idle
   * injection may append this event between turns without running the model.
   */
-  'user/message': UserMessageData
+  'user/message': UserMessage
  /** Raw stream chunk — token-level replay fidelity. */
  'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
  /**
@@ -66,7 +57,7 @@ interface SessionEventMap {
   * the model output and its accounting travel together (there is no separate
   * usage record). `usage` is absent when the adapter reported none.
   */
-  'assistant/message': { turn: number; step: number; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage }
+  'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
  /**
   * The model requested one tool invocation: `name` with the raw `arguments`
   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
@@ -87,14 +78,12 @@ interface SessionEventMap {
  'tool/result': {
    turn: number
    step: number
-    callId: CallId
-    content: ContentBlock[]
-    isError: boolean
+    message: ToolResultMessage
    error?: { name: string; code: string }
    meta?: JsonValue
  }
  /** Steering content injected between steps of a running turn. */
-  'steering/message': UserMessageData & { turn: number }
+  'steering/message': { turn: number; message: UserMessage }
  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
  'todo/write': { todos: TodoItem[] }
  /**
@@ -105,7 +94,7 @@ interface SessionEventMap {
 }
 ```

-`UserMessageData` is the durable `content` and `source` base shared by ordinary prompts, injected context, and steering. Live inbox events extend the same shape with an `AgentMessageId`; the loop adds only driver-owned routing state while an item remains pending.
+`UserMessage` is the identified, frozen user-role value shared by ordinary prompts, injected context, steering, and live inbox events. Event wrappers add only event-local position or outcome facts; the loop adds only driver-owned routing state while an item remains pending.

 ### `OutOfBandSessionEventMap` — narrow late-append opt-in

@@ -438,10 +427,9 @@ declare class Session {
   * The per-node pure function {@link deriveMessages} folds over the surface;
   * an external reconstructor (or the dev invariant) folds the same function
   * over a log prefix's surface to rebuild the exact messages any request was
-   * built from (the reconstructability Agent Note). The returned message wrapper is
-   * fresh; its content reuses the logged event's already deep-frozen durable
-   * data, so changing the wrapper cannot rewrite the log and changing content
-   * throws.
+   * built from (the reconstructability Agent Note). The returned message is
+   * the already frozen message nested in the event wrapper and shared by
+   * delivery, durable history, and model requests.
   * @param event - the event to project.
   * @returns the derived message, or null when the event produces none.
   */
--- a/docs/core-data-structures/session.zh.md
+++ b/docs/core-data-structures/session.zh.md
@@ -11,18 +11,9 @@
 仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.md) 添加了 `compact/start` / `compact/summary` / `compact/end`，`@deepseek-ai/dsh-hook-protocol` 添加了仅记录日志的 `hook/invoked` / `hook/result` 溯源事件，用于钩子桥接。与 `compact/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。

 ```ts type-equiv
-/**
- * Shared payload for user, injected-context, and steering messages. A
- * direct human prompt, a synthetic `agent.inject()` context, and mid-turn
- * steering all project into the model transcript as verbatim user-role content;
- * they are told apart by `source` (a non-`user` kind marks injected context),
- * not by event type.
- */
-interface UserMessageData {
-  /** Exact model-facing blocks. */
-  content: ContentBlock[]
-  /** Producer provenance. */
-  source: MessageSource
+/** A user-role specialization of the one shared message representation. */
+interface UserMessage extends Message {
+  readonly role: 'user'
 }
 ```

@@ -57,7 +48,7 @@ interface SessionEventMap {
   * project their `content` verbatim; `source` tells them apart. An idle
   * injection may append this event between turns without running the model.
   */
-  'user/message': UserMessageData
+  'user/message': UserMessage
  /** Raw stream chunk — token-level replay fidelity. */
  'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
  /**
@@ -66,7 +57,7 @@ interface SessionEventMap {
   * the model output and its accounting travel together (there is no separate
   * usage record). `usage` is absent when the adapter reported none.
   */
-  'assistant/message': { turn: number; step: number; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage }
+  'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
  /**
   * The model requested one tool invocation: `name` with the raw `arguments`
   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
@@ -87,14 +78,12 @@ interface SessionEventMap {
  'tool/result': {
    turn: number
    step: number
-    callId: CallId
-    content: ContentBlock[]
-    isError: boolean
+    message: ToolResultMessage
    error?: { name: string; code: string }
    meta?: JsonValue
  }
  /** Steering content injected between steps of a running turn. */
-  'steering/message': UserMessageData & { turn: number }
+  'steering/message': { turn: number; message: UserMessage }
  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
  'todo/write': { todos: TodoItem[] }
  /**
@@ -105,7 +94,7 @@ interface SessionEventMap {
 }
 ```

-`UserMessageData` 是普通提示词、注入上下文与 steering（中途引导）共享的持久 `content` + `source` 基础形状。实时收件箱事件在同一形状上扩展一个 `AgentMessageId`；条目待处理期间，loop 只额外附加驱动器自有的路由状态。
+`UserMessage` 是普通提示词、注入上下文、steering（中途引导）与实时收件箱事件共享的带标识且冻结的 user-role 值。事件包装层只会增加事件本地的位置或结果事实；条目待处理期间，loop 只额外附加驱动器自有的路由状态。

 ### `OutOfBandSessionEventMap`：受限的带外追加显式准入

@@ -440,10 +429,9 @@ declare class Session {
   * The per-node pure function {@link deriveMessages} folds over the surface;
   * an external reconstructor (or the dev invariant) folds the same function
   * over a log prefix's surface to rebuild the exact messages any request was
-   * built from (the reconstructability Agent Note). The returned message wrapper is
-   * fresh; its content reuses the logged event's already deep-frozen durable
-   * data, so changing the wrapper cannot rewrite the log and changing content
-   * throws.
+   * built from (the reconstructability Agent Note). The returned message is
+   * the already frozen message nested in the event wrapper and shared by
+   * delivery, durable history, and model requests.
   * @param event - the event to project.
   * @returns the derived message, or null when the event produces none.
   */
--- a/docs/core-data-structures/tools.i18n.yaml
+++ b/docs/core-data-structures/tools.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-tools.md: 65b1d398238d3779def303d2d3a36bd641778bd7
-tools.zh.md: 2fe3eb3dbca2447cfc06da25a930de92aae34898
+#   pnpm run verify-translation-pairing --write docs/core-data-structures/tools.md
+tools.md: dad7f7421caa94940801407fd4ef7fd936eb05c9
+tools.zh.md: 8386e5870e665e90ee0dbada8cb98084281001a7
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -215,7 +215,7 @@ interface ToolRunContext extends ToolExecution {
   * the agent loop. Contexts retain their individual source and metadata and
   * are emitted in call order.
   */
-  deferContext(context: UserMessageData): void
+  deferContext(context: UserMessage): void
  /**
   * Mark a successful final result as terminal for the current agent turn.
   * The marker rides this execution's own result (`concludesTurn` exists only
@@ -329,7 +329,7 @@ interface ToolExecutionSuccess {
  readonly content: ContentBlock[]
  readonly error?: never
  readonly meta?: JsonValue
-  readonly additionalContexts?: UserMessageData[]
+  readonly additionalContexts?: UserMessage[]
  /** The agent loop stops after committing this successful result batch. */
  readonly concludesTurn?: true
 }
@@ -343,7 +343,7 @@ interface ToolExecutionFailure {
  readonly value?: never
  readonly content: ContentBlock[]
  readonly meta?: JsonValue
-  readonly additionalContexts?: UserMessageData[]
+  readonly additionalContexts?: UserMessage[]
  readonly concludesTurn?: never
 }
 ```
@@ -380,9 +380,9 @@ type PreToolDecision =
 * next request, or block by turning corrective feedback into an error result.
 */
 type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessageData[] }
-  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessageData[] }
-  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessageData[] }
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] }
 ```

 Call `next()` for the default or return a decision to short-circuit. Pre-policy may deny or ask; only `allowed-once` proceeds, while a non-grant, missing approval channel or service, or agent-less request becomes a denial. Guards may still impose a final denial. Arguments cannot be rewritten because history, audit, UI, and execution must agree.
--- a/docs/core-data-structures/tools.zh.md
+++ b/docs/core-data-structures/tools.zh.md
@@ -215,7 +215,7 @@ interface ToolRunContext extends ToolExecution {
   * the agent loop. Contexts retain their individual source and metadata and
   * are emitted in call order.
   */
-  deferContext(context: UserMessageData): void
+  deferContext(context: UserMessage): void
  /**
   * Mark a successful final result as terminal for the current agent turn.
   * The marker rides this execution's own result (`concludesTurn` exists only
@@ -329,7 +329,7 @@ interface ToolExecutionSuccess {
  readonly content: ContentBlock[]
  readonly error?: never
  readonly meta?: JsonValue
-  readonly additionalContexts?: UserMessageData[]
+  readonly additionalContexts?: UserMessage[]
  /** The agent loop stops after committing this successful result batch. */
  readonly concludesTurn?: true
 }
@@ -343,7 +343,7 @@ interface ToolExecutionFailure {
  readonly value?: never
  readonly content: ContentBlock[]
  readonly meta?: JsonValue
-  readonly additionalContexts?: UserMessageData[]
+  readonly additionalContexts?: UserMessage[]
  readonly concludesTurn?: never
 }
 ```
@@ -380,9 +380,9 @@ type PreToolDecision =
 * next request, or block by turning corrective feedback into an error result.
 */
 type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessageData[] }
-  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessageData[] }
-  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessageData[] }
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] }
 ```

 调用 `next()` 获取默认决策，或直接返回一个决策以短路。前置策略可以 deny 或 ask；只有 `allowed-once` 才继续执行，而未授权、缺少审批通道或服务、或无 agent 的请求都会变为拒绝。Guard 仍可施加最终拒绝。参数不可被改写，因为历史记录、审计、UI 和执行必须保持一致。