@deepseek-ai/dsh-session 0.1.5-rc.2 → 0.1.6-alpha.1

package/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/session/README.md
-README.md: cdcab8ec4d2f6960bb651aff46745b20f91632e2
-README.zh.md: 745615f67084430475e0739b22afa35556b71ee6
+README.md: 8d07292287d7300b562751ad74de77397bd5b5db
+README.zh.md: 28b6f1f02838420861a76409046c0e9a12bac1b5

package/README.md

@@ -49,13 +49,15 @@ session.deriveMessages()         // the derived model history
 
 Surface events (`system/message`, `user/message`, `assistant/message`, `tool/result`) require `surfaceOp` in both typed events and append input. A replacement uses exactly `{ op: 'replace', startSeq, endSeq }`, with inclusive `SessionSeq` endpoints in current surface order. An Assistant message embeds its exact compact provider stream and forbids `sourceEventSeqs`. Known log-only events forbid both metadata fields and never produce a message.
 
+Plugins declare content-changing events with `@messageProjection` and register a pure definition through `ctx.sessions.registerMessageProjection()`. Session calls the definition before accepting an event and caches its immutable message updates. Missing definitions reject append and restore; unloading a used definition also blocks cached reads. Detached constructors and `foldSurface(events, projections)` require explicit definitions. Reconstructors pass the fold's `projectedMessages` to `deriveEventMessage()`; live instance methods apply the same projections automatically. [Plugin-owned message projections](../../../.agents/notes/implemented/architecture/2026-09-11-plugin-owned-message-projections.md) defines ownership and offline assembly.
+
 Append, seed/restore, and event adoption/snapshot reject any `header.system` and exactly empty optional request-header fields (`tools: []`, `adapterDefaults: {}`) instead of normalizing input. Tool-result `data.error` is allowed only when `message.content[0].isError === true`; failure identity remains optional. Rejected appends do not change the log, derived state, or event feed. Adoption validates event-local metadata but not referenced history or replacement membership.
 
 `system/message` holds the rendered system prompt: the first one is surface node 0, the prepared call capability governs admission, with a non-empty rendering consolidated at the first system node on an incapable route or appended after cached history inside a continuing `in-history` series; empty system nodes project to no message, so clearing the prompt requires logged empty replacements of all active system nodes, not just the latest; the surface fold rejects a replacement covering node 0 while it is a `system/message` unless the replacing event is itself a `system/message` over exactly that node, while later system nodes carry no protection and a compaction range may shadow them ([decision](../../../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md)).
 
 ### Read the log
 
-`session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. Callers that only need a length or one event use `seq` or `eventAt()`.
+`session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. `eventAt()`, `snapshotEvents()`, and `ownEvents()` are deprecated: existing logic may remain unmigrated for now, but new production calls are prohibited. Repository test files may use these three readers under their scoped lint allowance ([policy](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md)). Callers that only need a length use `seq`.
 
 Session log positions use two numeric types. `SessionSeq` identifies an existing event or inclusive event watermark; `SessionLogOffset` identifies a gap, prefix length, or read boundary and may equal the event count. `SessionSeqCursor` adds the `-1` “no event yet” value, while `OptionalSessionSeq` uses `null` when absence is data. The constructors validate non-negative safe integers, and the brands disappear at runtime, so durable JSON and wire values remain ordinary numbers.
 
@@ -81,11 +83,11 @@ This section explains how the package realizes the behavior above; the observabl
 
 ### Design concept
 
-The package is built on event sourcing: a `Session` is an append-only log of typed `SessionEvent`s, and everything else — model history, transcripts, telemetry, titles, persistence — derives from that stream. The surface is a derived projection: an incremental manager validates append candidates, advances the ordered view from committed events, and tracks a `replaceGeneration` that bumps on every committed rewrite. Model-visible means logged: anything that reaches a model request must be reconstructable from the log. Each model attempt that reaches settlement commits one event: `assistant/message` carries the assembled model-visible message plus its compact timed stream, while `assistant/attempt` retains a failed, retried, cancelled, or stream-error attempt without adding model history. A hard process loss before settlement leaves no durable attempt stream.
+The package is built on event sourcing: a `Session` is an append-only log of typed `SessionEvent`s, and everything else — model history, transcripts, telemetry, titles, persistence — derives from that stream. The surface is a derived projection: an incremental manager validates append candidates, advances the ordered view from committed events, and tracks `replaceGeneration` for positional replacements and `contentGeneration` for replacements and plugin-owned message changes. Model-visible means logged: anything that reaches a model request must be reconstructable from the log. Each model attempt that reaches settlement commits one event: `assistant/message` carries the assembled model-visible message plus its compact timed stream, while `assistant/attempt` retains a failed, retried, cancelled, or stream-error attempt without adding model history. A hard process loss before settlement leaves no durable attempt stream.
 
 ### Request headers
 
-`request/header` stores a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, `change`, or `series`. An explicit message-series start or a surface replacement writes a `series` snapshot when the envelope is unchanged; a simultaneous change uses `startsSeries: true`. Same-series steps, retries, and ordinary later turns inherit the latest snapshot. `adapterDefaults` distinguishes values resolved by the adapter from explicit settings, and `foldRequestHeader()` selects the latest snapshot. This self-contained record supports partial-window rendering and exact reconstruction at the cost of growth per message series; the [reconstructable-requests Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md) owns the detail.
+`request/header` stores a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, `change`, or `series`. An explicit message-series start, a surface replacement, or a plugin-owned message change writes a `series` snapshot when the envelope is unchanged; a simultaneous change uses `startsSeries: true`. Same-series steps, retries, and ordinary later turns inherit the latest snapshot. `adapterDefaults` distinguishes values resolved by the adapter from explicit settings, and `foldRequestHeader()` selects the latest snapshot. This self-contained record supports partial-window rendering and exact reconstruction at the cost of growth per message series; the [reconstructable-requests Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md) owns the detail.
 
 ### Source map
 
@@ -105,7 +107,7 @@ Every append uses the shared iterative `snapshotJsonValue()` pass, which reads,
 
 ### Derived history
 
-`deriveMessages()` caches each surface node's projection once and returns a fresh array per call over shared, deep-frozen messages; each of the four surface event types (`system/message`, `user/message`, `assistant/message`, `tool/result`) projects its own message kind — the system-role prompt (an empty-content system node projects to no message), user content verbatim, the assembled assistant message with its provider and model, or a user-role tool result. Embedded Assistant streams and `assistant/attempt` events remain replay and diagnostic data only. A surface rewrite rebuilds the projection — there is no raw-log fallback, so the surface is the single source of derived history.
+`deriveMessages()` caches deep-frozen projections and returns a fresh array per call. The four surface event types (`system/message`, `user/message`, `assistant/message`, `tool/result`) supply their recorded message identities and content; an empty-content system node projects to no message. Plugin-owned projections change derived content without mutating recorded messages. Replacements and projection decisions invalidate the cache. Embedded Assistant streams and `assistant/attempt` events remain replay and diagnostic data only.
 
 ### The request header
 
@@ -135,7 +137,7 @@ The package-level contract is enough for most consumers; read these when you nee
 
 #### What the model sees
 
-The model receives the complete messages from `system/message`, `user/message`, `assistant/message`, and `tool/result` surface entries verbatim, the system prompt first — identities, roles, sources, and content blocks are the same values established at creation, and projections never mint identities. Direct prompts and injected context remain separate `user/message` events whose sources preserve their provenance. Embedded streams, `assistant/attempt`, boundaries, and other log-only facts add no message.
+The model receives the complete messages from `system/message`, `user/message`, `assistant/message`, and `tool/result` surface entries with logged projections applied, the system prompt first. Identities, roles, sources, and unmodified blocks retain their original values; projections never mint identities. Direct prompts and injected context remain separate `user/message` events whose sources preserve their attribution. Embedded streams, `assistant/attempt`, boundaries, and other log-only facts add no message.
 
 #### Token effect
 
@@ -181,7 +183,7 @@ Logging causes no invalidation, and exact reconstruction preserves request-prefi
 These limits define when the session store needs special care. They are current package constraints, not a task backlog.
 
 - **`fork()` cuts only at stable boundaries of live sessions** — the selected prefix must end outside an open turn and the source must be in the store; forking a persisted-but-unloaded session is excluded from the fork API.
-- **`SESSION_FORMAT_VERSION` names the [current logical representation](../../../docs/session-format-status.md)** — the current reader rejects retired `header.system` and validates `system/message` payloads and protected-head rewrites. Historical headers and events belong to adjacent format packages; the adjacent migration chain converts supported history before constructing `Session`, and write open publishes only the current-format successor. Equal-version unknown events require the envelope's explicit `ignorable` marker, which does not promise safe structural migration ([mechanism](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md)).
+- **`SESSION_FORMAT_VERSION` names the [current logical representation](../../../docs/session-format-status.md)** — the current reader rejects retired `header.system` and validates `system/message` payloads and protected-head rewrites. Historical headers and events belong to adjacent format packages; the adjacent migration chain converts supported history before constructing `Session`, and the write-open path publishes only the current-format successor. Equal-version unknown events require the envelope's explicit `ignorable` marker, which does not promise safe structural migration ([mechanism](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md)).
 - **`TurnEndReasonMap` omits the ACP-named `refusal` / `max_turn_requests` variants** — producer-gated: they land when an adapter or the loop first emits them.
 - **No session tree beyond fork** — a pi-style entry tree over branched sessions is deferred unless a consumer needs more than boundary-based forking.
 

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "面向用户与维护者的事件溯源会话日志与内存存储说明，用于构建、检查或扩展每个 agent 交互背后的持久记录。"
+description: "面向用户与维护者的事件溯源会话日志与内存存储说明，用于构建、检查或扩展每个 agent（智能体）交互背后的持久记录。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-session` 在仅追加的会话日志中记录每个模型可见事实，并从该记录派生模型历史。消费方可以检查、回放、派生和刷新会话，同时保留历史事件；压缩会在活跃对话中隐藏被取代的条目，但不会删除它们。除非添加持久化后端，否则会话仅保留在内存中；持久性检查点会等待配置的后端。agent 需要可重建的会话记录时请选择本包；它本身不调用模型。
+`dsh-session` 在仅追加的会话日志中记录每个模型可见事实，并从该记录派生模型历史。消费方可以检查、回放、fork 和刷新会话，同时保留历史事件；压缩（compaction）会在活跃对话中隐藏被取代的条目，但不会删除它们。除非添加持久化后端，否则会话仅保留在内存中；持久性检查点会等待配置的后端。agent 需要可重建的会话记录时请选择本包；它本身不调用模型。
 
 ## 目录
 
@@ -47,7 +47,9 @@ session.append('user/message', { role: 'user', content: [{ type: 'text', text: '
 session.deriveMessages()         // the derived model history
 ```
 
-表层事件（`system/message`、`user/message`、`assistant/message`、`tool/result`）在类型化事件与追加输入中都必须带有 `surfaceOp`。替换操作仅接受 `{ op: 'replace', startSeq, endSeq }`，端点为包含边界的 `SessionSeq`，按当前 surface 顺序解释。Assistant message 嵌入其精确紧凑 provider stream，并禁止 `sourceEventSeqs`。已知仅日志事件禁止这两个元数据字段，且从不产生消息。
+表层事件（`system/message`、`user/message`、`assistant/message`、`tool/result`）在类型化事件与追加输入中都必须带有 `surfaceOp`。替换操作仅接受 `{ op: 'replace', startSeq, endSeq }`，端点为包含边界的 `SessionSeq`，按当前 surface 顺序解释。assistant 消息会嵌入精确、紧凑的提供方流，并禁止 `sourceEventSeqs`。已知仅日志事件禁止这两个元数据字段，且从不产生消息。
+
+插件用 `@messageProjection` 声明修改内容的事件，并通过 `ctx.sessions.registerMessageProjection()` 注册纯处理器。Session 在接受事件前调用处理器，并缓存其不可变消息更新。缺少处理器时拒绝追加和恢复，卸载已经使用的处理器后也会拒绝读取缓存。独立构造函数和 `foldSurface(events, projections)` 必须显式接收处理器。重建函数将折叠结果的 `projectedMessages` 传给 `deriveEventMessage()`，实时实例方法自动应用相同的投影。[插件拥有消息投影](../../../.agents/notes/implemented/architecture/2026-09-11-plugin-owned-message-projections.zh.md)说明职责划分和离线装配。
 
 追加、seed/restore 与事件 adoption/snapshot 会拒绝任何 `header.system` 及恰好为空的可选请求头字段（`tools: []`、`adapterDefaults: {}`），而不规范化输入。工具结果的 `data.error` 仅在 `message.content[0].isError === true` 时允许存在；失败标识仍是可选的。被拒绝的追加不会改变日志、派生状态或事件流。Adoption 校验事件局部元数据，但不校验所引用的历史或替换端点是否属于 surface。
 
@@ -55,19 +57,19 @@ session.deriveMessages()         // the derived model history
 
 ### 读取日志
 
-`session.seq` 无需物化数组即可读取当前日志长度，`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照；当前完整快照会缓存到下一次追加。只需要长度或单个事件的调用方使用 `seq` 或 `eventAt()`。
+`session.seq` 无需物化数组即可读取当前日志长度，`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照；当前完整快照会缓存到下一次追加。`eventAt()`、`snapshotEvents()` 和 `ownEvents()` 已弃用：现有逻辑可以暂不迁移，但禁止新增生产调用。仓库测试文件可以在限定范围的 lint 豁免下使用这三个读取方法（[策略](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.zh.md)）。只需要长度的调用方使用 `seq`。
 
-会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位；`SessionLogOffset` 标识间隙、前缀长度或读取边界，并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值，`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数，品牌在运行时会被擦除，因此持久 JSON 与 wire 值仍是普通数字。
+会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位；`SessionLogOffset` 标识间隙、前缀长度或读取边界，并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值，`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数，brand 在运行时会被擦除，因此持久 JSON 与 wire 值仍是普通数字。
 
 ### 派生会话的 fork
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` 选取截至 `boundary` 事件序号（含该事件）的源事件（默认：当前最后一个事件），要求所选前缀结束时没有开放轮次，再创建带谱系元数据的实时子会话。必须在轮次中途分支的工具时委派会裁剪到已完成前缀。
 
-逻辑 `SessionHeader.isSeeded` 字段报告是否存在 fork 历史，而不公开位置整数。`Session.inheritedEventCount` 保留经过校验的精确 `SessionLogOffset`；`ownEvents()` 返回从该切点开始的事件，`isOwnSeq(seq)` 只接受已存在且由 child 拥有的位置。底层带 seed 构造必须显式提供 `seed` 与 `inheritedEventCount`，因为构造 seed 可以在继承前缀之后包含 child 自有的设置事件。
+逻辑 `SessionHeader.isSeeded` 字段报告是否存在 fork 历史，而不公开位置整数。`Session.inheritedEventCount` 保留经过校验的精确 `SessionLogOffset`；`ownEvents()` 返回从该切点开始的事件，`isOwnSeq(seq)` 只接受已存在且由子会话拥有的位置。底层带 seed 构造必须显式提供 `seed` 与 `inheritedEventCount`，因为构造 seed 可以在继承前缀之后包含子会话自有的设置事件。
 
 ### 刷新持久状态
 
-`ctx.sessions.flush(session)` 分发需等待完成的持久性检查点：每个持久化监听器都会刷新，调用在所有监听器结算后完成。需要立即持久性屏障的生产方应等待它，而不是假定写后刷新已完成。
+`ctx.sessions.flush(session)` 分发需等待完成的持久性检查点：每个持久化监听器都会刷新，调用在所有监听器结算后完成。需要立即持久性屏障的生产方应等待它，而不是假定延后写入已经排空。
 
 -----
 
@@ -81,11 +83,11 @@ session.deriveMessages()         // the derived model history
 
 ### 设计理念
 
-该包建立在事件溯源之上：`Session` 是类型化 `SessionEvent` 的仅追加日志，其他一切——模型历史、transcript、遥测、标题、持久化——都从这条流派生。surface 是派生投影：一个增量管理器校验追加候选、根据已提交事件推进有序视图，并跟踪每次已提交重写都会递增的 `replaceGeneration`。模型可见即已记录：任何到达模型请求的内容都必须能从日志重建。每个到达 settlement 的模型 attempt 都会提交一个事件：`assistant/message` 携带组装后的模型可见 message 及其紧凑带时间 stream，`assistant/attempt` 则保留失败、重试、取消或 stream error attempt，且不添加模型历史。如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
+该包建立在事件溯源之上：`Session` 是类型化 `SessionEvent` 的仅追加日志，其他一切——模型历史、transcript（文本记录）、遥测、标题、持久化——都从这条流派生。surface 是派生投影：一个增量管理器校验追加候选、根据已提交事件推进有序视图，通过 `replaceGeneration` 跟踪位置替换，通过 `contentGeneration` 跟踪位置替换和插件拥有的消息变更。模型可见即已记录：任何到达模型请求的内容都必须能从日志重建。每个完成结算的模型尝试都会提交一个事件：`assistant/message` 携带组装后的模型可见 message 及其紧凑带时间 stream，`assistant/attempt` 则保留失败、重试、取消或 stream error attempt，且不添加模型历史。如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
 
-### 请求 header
+### 请求头
 
-`request/header` 存储非历史请求 envelope 的完整规范快照，原因为 `initial`、`resume`、`change` 或 `series`。显式消息序列起点或表层替换会在 envelope 不变时写入 `series` 快照；同时发生变化时使用 `startsSeries: true`。同一序列内的步骤、重试与普通后续轮次继承最新快照。`adapterDefaults` 区分由适配器解析的值与显式设置，`foldRequestHeader()` 选择最新快照。这种自包含记录以每个消息序列增加存储为代价，支持局部窗口渲染与精确重建；细节由[可重建请求 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md)负责。
+`request/header` 存储非历史请求封装的完整规范快照，原因为 `initial`、`resume`、`change` 或 `series`。显式消息序列起点、表层替换或插件拥有的消息变更会在请求封装不变时写入 `series` 快照；同时发生变化时使用 `startsSeries: true`。同一序列内的步骤、重试与普通后续轮次继承最新快照。`adapterDefaults` 区分由适配器解析的值与显式设置，`foldRequestHeader()` 选择最新快照。这种自包含记录以每个消息序列增加存储为代价，支持局部窗口渲染与精确重建；细节由[可重建请求 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md)负责。
 
 ### 源码地图
 
@@ -105,7 +107,7 @@ session.deriveMessages()         // the derived model history
 
 ### 派生历史
 
-`deriveMessages()` 把每个 surface 节点的投影缓存一次，每次调用都返回共享、深度冻结消息之上的新数组；四种 surface 事件类型（`system/message`、`user/message`、`assistant/message`、`tool/result`）各自投影自己的消息种类——system 角色的提示词（空内容的系统节点投影为无消息）、user 内容原样、带提供方与模型的组装 assistant 消息，或 user 角色的工具结果。嵌入式 Assistant stream 与 `assistant/attempt` 事件只保留重放和诊断数据。surface 重写会重建投影——不存在原始日志回退，因此 surface 是派生历史的唯一来源。
+`deriveMessages()` 缓存深度冻结的派生消息，每次调用返回新数组。四种 surface 事件类型（`system/message`、`user/message`、`assistant/message`、`tool/result`）提供记录的消息身份和内容，空内容的系统节点不派生消息。插件拥有的投影修改派生内容，不修改记录的消息。替换和投影决策使缓存失效。嵌入式 Assistant stream 与 `assistant/attempt` 事件只保留回放和诊断数据。
 
 ### 请求头
 
@@ -135,7 +137,7 @@ session.deriveMessages()         // the derived model history
 
 #### 模型看到什么
 
-模型会原样接收 `system/message`、`user/message`、`assistant/message` 与 `tool/result` surface 条目中的完整消息，系统提示词在先——标识、角色、来源与内容块都与创建时确定的值相同，投影从不生成标识。直接提示词与注入上下文仍是彼此独立的 `user/message` 事件，各事件的来源会保留其出处。嵌入式 stream、`assistant/attempt`、边界与其他仅日志事实不会添加消息。
+模型会接收 `system/message`、`user/message`、`assistant/message` 与 `tool/result` surface 条目中的消息，并应用日志中的投影，系统提示词在先。消息标识、角色、来源及未修改的内容块保持不变，投影不生成标识。直接提示词与注入上下文仍是独立的 `user/message` 事件，各事件的来源保留其出处。嵌入式 stream、`assistant/attempt`、边界与其他仅日志事实不添加消息。
 
 #### Token 影响
 

package/lib/index.js

@@ -97,6 +97,7 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"goal/change",
 	"hook/invoked",
 	"hook/result",
+	"image/offload",
 	"llm/retry",
 	"llm/retry-started",
 	"model/selection",
@@ -134,6 +135,8 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"user/message",
 	"web/deepseek-search-llm-request"
 ]);
+/** Event types whose model-visible effects require an explicit pure interpreter. */
+const MESSAGE_PROJECTION_EVENT_TYPES = new Set(["image/offload"]);
 //#endregion
 //#region lib/types/surface.js
 /**
@@ -196,17 +199,18 @@ function isReplacementSurfaceEvent(event) {
 /**
 * Project a single event into the LLM message it derives to, or null when it
 * produces none — a non-surface event (attempt, boundary, log-only record) or an
-* empty-content assistant/message (which exists only to host usage). This is
-* THE per-node projection rule: `Session.deriveMessages` folds it over the
-* live surface, external reconstructors and pure projections fold the same
-* function over a log prefix's surface to rebuild the exact messages any
-* request was built from. The returned message is the already frozen message
-* nested in the event wrapper and shared by delivery, durable history, and
-* model requests.
+* empty-content assistant/message (which exists only to host usage). A caller
+* reconstructing model input supplies the same prefix's `projectedMessages`
+* from {@link foldSurface}; without that map this function reads original
+* event content. Session instance methods apply the live projection. Messages
+* are immutable and unchanged content retains its durable identity.
 * @param event - the event to project.
+* @param projectedMessages - message projections from the same log prefix's surface fold.
 * @returns the derived message, or null when the event produces none.
 */
-function deriveEventMessage(event) {
+function deriveEventMessage(event, projectedMessages) {
+	const projected = projectedMessages?.get(event.seq);
+	if (projected !== void 0) return projected;
 	switch (event.type) {
 		case "user/message": return event.data;
 		case "system/message":
@@ -251,7 +255,10 @@ function validateSessionEventData(event, subject) {
 function createFoldState() {
 	return {
 		nodes: [],
-		replaceGeneration: 0
+		replaceGeneration: 0,
+		contentGeneration: 0,
+		projectedMessages: /* @__PURE__ */ new Map(),
+		projections: /* @__PURE__ */ new Set()
 	};
 }
 /** Whether a runtime value is a non-negative safe event sequence. */
@@ -280,7 +287,7 @@ function surfaceOpOf(event) {
 	return op;
 }
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
-function assertProvenance(event, shadowedSeqs) {
+function assertSourceEventReferences(event, shadowedSeqs) {
 	const raw = event.sourceEventSeqs;
 	if (event.type === "assistant/message" && raw !== void 0) throw new Error("assistant/message embeds its source stream and cannot carry sourceEventSeqs");
 	const sources = /* @__PURE__ */ new Set();
@@ -309,7 +316,7 @@ function assertProvenance(event, shadowedSeqs) {
 function validateSurfaceMetadata(event) {
 	const op = surfaceOpOf(event);
 	if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
-	if (op !== void 0) assertProvenance(event, []);
+	if (op !== void 0) assertSourceEventReferences(event, []);
 	return op;
 }
 /** Locate one replacement range without mutating the current fold state. */
@@ -382,16 +389,28 @@ function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, b
 	if (event.type !== "system/message" || shadowedSeqs.length !== 1) throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
 }
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
-function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+function planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
 	if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
 	const surfaceOp = validateSurfaceMetadata(event);
+	const projection = projections.find((item) => item.type === event.type);
+	if (projection !== void 0) return {
+		kind: "project",
+		projection,
+		messages: projection.project(event, {
+			nodes: state.nodes,
+			events,
+			baseSeq,
+			messages: state.projectedMessages
+		})
+	};
+	if (MESSAGE_PROJECTION_EVENT_TYPES.has(event.type)) throw new Error(`session event "${event.type}" requires a message projection; load its owning plugin or supply its projection definition`);
 	if (surfaceOp === void 0) return;
 	if (surfaceOp === "append") return {
 		kind: "append",
 		seq: event.seq
 	};
 	const range = replacementRange(state, surfaceOp);
-	assertProvenance(event, range.shadowedSeqs);
+	assertSourceEventReferences(event, range.shadowedSeqs);
 	assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
 	assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
 	return {
@@ -403,8 +422,8 @@ function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
 	};
 }
 /** Apply one event and return replacement metadata only when one occurred. */
-function applySurfaceEvent(state, event, expectedSeq, events, baseSeq) {
-	return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq));
+function applySurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
+	return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections));
 }
 /** Commit one previously validated surface transition. */
 function applySurfacePlan(state, plan) {
@@ -412,6 +431,11 @@ function applySurfacePlan(state, plan) {
 	else if (plan?.kind === "replace") {
 		state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
 		state.replaceGeneration += 1;
+		state.contentGeneration += 1;
+	} else if (plan?.kind === "project") {
+		for (const [seq, message] of plan.messages) state.projectedMessages.set(seq, message);
+		state.projections.add(plan.projection);
+		state.contentGeneration += 1;
 	}
 	if (plan?.kind !== "replace") return;
 	return {
@@ -424,25 +448,28 @@ function applySurfacePlan(state, plan) {
 /**
 * Replay a complete session log through the canonical surface fold.
 * @param events - session events in contiguous seq order.
+* @param projections - pure interpreters for plugin-owned message changes; required definitions must be supplied.
 * @returns detached current sequences and replacement history.
-* @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
+* @throws when an interpreter is missing or an event violates its projection, surface metadata, source attribution, or replacement rules.
 */
-function foldSurface(events) {
+function foldSurface(events, projections = []) {
 	const state = createFoldState();
 	const replacements = [];
 	for (const [index, event] of events.entries()) {
-		const replacement = applySurfaceEvent(state, event, SessionSeq(index), events, SessionLogOffset(0));
+		const replacement = applySurfaceEvent(state, event, SessionSeq(index), events, SessionLogOffset(0), projections);
 		if (replacement !== void 0) replacements.push(replacement);
 	}
 	return {
 		nodes: [...state.nodes],
-		replacements
+		replacements,
+		projectedMessages: new Map(state.projectedMessages)
 	};
 }
 /** Incremental ordered surface view and append-boundary validator. */
 var SurfaceManager = class {
 	log;
 	baseSeq;
+	projections;
 	/** Shared transition state; replacement history is not retained. */
 	_state = createFoldState();
 	/** Last processed absolute seq. */
@@ -452,10 +479,12 @@ var SurfaceManager = class {
 	/**
 	* @param log - Contiguous complete log or loaded event window.
 	* @param baseSeq - Absolute sequence of the window's first event.
+	* @param projections - live borrowed definitions; removing a used definition invalidates further reads.
 	*/
-	constructor(log, baseSeq = SessionLogOffset(0)) {
+	constructor(log, baseSeq = SessionLogOffset(0), projections = []) {
 		this.log = log;
 		this.baseSeq = baseSeq;
+		this.projections = projections;
 		this._lastProcessedSeq = baseSeq === 0 ? -1 : SessionSeq(baseSeq - 1);
 	}
 	/**
@@ -463,21 +492,40 @@ var SurfaceManager = class {
 	* @param event - candidate event that has not entered the log yet.
 	*/
 	validateNext(event) {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		const expectedSeq = SessionSeq(this.baseSeq + this.log.length);
 		this._pendingPlan = {
 			event,
 			expectedSeq,
-			plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq)
+			plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq, this.projections)
 		};
 	}
 	/** Monotonic count of folded positional replacements. */
 	get replaceGeneration() {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		return this._state.replaceGeneration;
 	}
+	/** Monotonic count of committed changes to existing model-visible content. */
+	get contentGeneration() {
+		this._assertProjections();
+		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
+		return this._state.contentGeneration;
+	}
+	/**
+	* Project one message with every committed message projection applied.
+	* @param event - message-producing or log-only event.
+	* @returns its immutable projected message, or null when it produces none.
+	*/
+	deriveEventMessage(event) {
+		this._assertProjections();
+		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
+		return deriveEventMessage(event, this._state.projectedMessages);
+	}
 	/** Surface event sequences in model-visible order. */
 	get nodes() {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		return this._state.nodes;
 	}
@@ -489,11 +537,18 @@ var SurfaceManager = class {
 			const event = this.log[index];
 			const pending = this._pendingPlan;
 			if (pending?.event === event && pending.expectedSeq === seq) applySurfacePlan(this._state, pending.plan);
-			else applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq);
+			else applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq, this.projections);
 			if (pending !== void 0 && pending.expectedSeq <= seq) this._pendingPlan = void 0;
 			this._lastProcessedSeq = SessionSeq(seq);
 		}
 	}
+	/** Cached messages cannot outlive the definitions that interpreted their log. */
+	_assertProjections() {
+		const candidate = this._pendingPlan;
+		const pending = candidate !== void 0 && this.log[candidate.expectedSeq - this.baseSeq] === candidate.event ? candidate.plan : void 0;
+		const required = pending?.kind === "project" ? [...this._state.projections, pending.projection] : this._state.projections;
+		for (const projection of required) if (!this.projections.includes(projection)) throw new Error(`session message projection "${projection.type}" was removed or replaced; restore the session with its owning plugin`);
+	}
 };
 //#endregion
 //#region lib/types/request-header.js
@@ -988,7 +1043,7 @@ const attachments = /* @__PURE__ */ new WeakMap();
 var Session = class Session {
 	log = [];
 	/** Single incremental owner of surface acceptance and projection state. */
-	surfaceManager = new SurfaceManager(this.log);
+	surfaceManager;
 	/** The ordered surface over this session's event log. */
 	get surface() {
 		return this.surfaceManager;
@@ -1039,10 +1094,12 @@ var Session = class Session {
 	* @param seed - optional borrowed replay or fork events.
 	* @param header - optional borrowed storage metadata.
 	* @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
+	* @param projections - pure interpreters for plugin-owned message changes.
 	* @returns a detached session.
+	* @throws when a seed event requires a missing message interpreter or fails validation.
 	*/
-	static create(id, seed, header, inheritedEventCount) {
-		return new Session(id, seed, header, "snapshot", inheritedEventCount);
+	static create(id, seed, header, inheritedEventCount, projections) {
+		return new Session(id, seed, header, "snapshot", inheritedEventCount, projections);
 	}
 	/**
 	* Restore a detached session by adopting an independently owned or deeply frozen seed.
@@ -1055,12 +1112,15 @@ var Session = class Session {
 	* @param header - independently owned storage metadata.
 	* @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
 	* @param eventState - aliasing state carried from the operation that produced the seed.
+	* @param projections - pure interpreters for plugin-owned message changes.
 	* @returns a restored detached session.
+	* @throws when a seed event requires a missing message interpreter or fails validation.
 	*/
-	static fromRestore(id, seed, header, inheritedEventCount, eventState) {
-		return new Session(id, seed, header, eventState, inheritedEventCount);
+	static fromRestore(id, seed, header, inheritedEventCount, eventState, projections) {
+		return new Session(id, seed, header, eventState, inheritedEventCount, projections);
 	}
-	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount) {
+	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount, projections = []) {
+		this.surfaceManager = new SurfaceManager(this.log, SessionLogOffset(0), projections);
 		const restoredHeader = mode === "snapshot" ? void 0 : validateRestoredSessionHeader(id, header);
 		if (seed !== void 0) for (const [index, source] of seed.entries()) {
 			const snapshot = mode === "snapshot" ? snapshotJsonValue(source) : source;
@@ -1090,6 +1150,8 @@ var Session = class Session {
 	eventsSnapshot;
 	/**
 	* Return the immutable event stored at one exact sequence number.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @param seq - event sequence number.
 	* @returns the accepted event, or undefined when the log does not contain it.
 	*/
@@ -1100,6 +1162,8 @@ var Session = class Session {
 	* Materialize an immutable snapshot of a half-open event sequence range.
 	* A full current snapshot is reused until the next append; every previously
 	* returned snapshot remains stable after later appends.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @param fromSeq - non-negative inclusive sequence number; defaults to the log start.
 	* @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
 	* @returns a frozen array of the selected deeply frozen events.
@@ -1113,6 +1177,8 @@ var Session = class Session {
 	}
 	/**
 	* Return this Session's events after its fork-inherited prefix.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @returns a fresh array containing child-owned events in log order.
 	*/
 	ownEvents() {
@@ -1246,7 +1312,7 @@ var Session = class Session {
 	derived = [];
 	/** Surface position (nodes projected) the cache has reached. */
 	derivedNodes = 0;
-	/** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+	/** {@link SurfaceManager.contentGeneration} the cache was built under. */
 	derivedGeneration = 0;
 	/**
 	* Derive the LLM message history by walking the ordered sequences of
@@ -1255,21 +1321,21 @@ var Session = class Session {
 	* append records its `surfaceOp`, so a raw event with no marker (a chunk, a
 	* turn boundary) is correctly absent, and a compaction `replace` deletes the
 	* shadowed nodes from the derivation. The projection rules are
-	* {@link deriveEventMessage}, folded per node.
+	* {@link deriveEventMessage}, with logged message projections applied
+	* without changing node membership or message identity.
 	*
-	* CACHED: each surface node is projected exactly once, when first seen — a
-	* call costs O(new nodes), and a surface rewrite (a `replace`;
-	* {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+	* CACHED: pure tail growth costs O(new nodes); a replacement or message projection
+	* ({@link SessionSurface.contentGeneration}) rebuilds. The returned array is
 	* a fresh snapshot per call (later appends never grow an array a caller
 	* already holds); the `Message` objects in it are SHARED and **deep-frozen**.
-	* Their content reuses the already frozen durable event data, so the cache
-	* needs no second deep clone and consumers still cannot mutate the log.
+	* Unchanged content reuses frozen event data; projected blocks are frozen
+	* derived copies. Consumers cannot mutate the log through either form.
 	* @returns a fresh array of the shared, frozen derived history.
 	*/
 	deriveMessages() {
 		const surface = this.surface;
 		const nodes = surface.nodes;
-		const generation = surface.replaceGeneration;
+		const generation = surface.contentGeneration;
 		if (generation !== this.derivedGeneration) {
 			this.derived = [];
 			this.derivedNodes = 0;
@@ -1283,13 +1349,13 @@ var Session = class Session {
 		return [...this.derived];
 	}
 	/**
-	* Instance face of the pure per-node `deriveEventMessage` export from
-	* `surface.ts`.
+	* Project one event with all committed message projections applied.
+	* The original durable event remains unchanged.
 	* @param event - the event to project.
 	* @returns the derived message, or null when the event produces none.
 	*/
 	deriveEventMessage(event) {
-		return deriveEventMessage(event);
+		return this.surfaceManager.deriveEventMessage(event);
 	}
 };
 /** Typed error for session fork rejections. */
@@ -1311,6 +1377,27 @@ var SessionForkError = class extends Error {
 var SessionStore = class extends Service {
 	store = /* @__PURE__ */ new Map();
 	counter = 0;
+	projections = [];
+	/** Borrowed definitions for detached replay; contributions live until their registering fibers unload. */
+	get messageProjections() {
+		return this.projections;
+	}
+	/**
+	* Register one event interpreter for live creation, restore, and fork.
+	* Disposing the contribution makes sessions that used it refuse further derivation.
+	* @param projection - pure definition owned by the event's plugin.
+	* @returns the fiber-owned disposer.
+	* @throws when another definition already owns this event type.
+	*/
+	registerMessageProjection(projection) {
+		if (this.projections.some((item) => item.type === projection.type)) throw new Error(`session message projection "${projection.type}" is already registered`);
+		return this.ctx.effect(() => {
+			this.projections.push(projection);
+			return () => {
+				this.projections.splice(this.projections.indexOf(projection), 1);
+			};
+		}, "sessions.registerMessageProjection()");
+	}
 	constructor(ctx) {
 		super(ctx, "sessions");
 		ctx.inject(["typert"], (typeCtx) => {
@@ -1382,7 +1469,7 @@ var SessionStore = class extends Service {
 			const { eventState } = options;
 			switch (eventState) {
 				case "detached":
-				case "shared-frozen": return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState);
+				case "shared-frozen": return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
 				case void 0: break;
 				/* v8 ignore next -- closed-union exhaustiveness guard */
 				default: assertNever(eventState, "SessionStore.prepare event state");
@@ -1401,7 +1488,7 @@ var SessionStore = class extends Service {
 			...meta?.delegationDepth === void 0 ? {} : { delegationDepth: meta.delegationDepth },
 			...meta?.agentPreset === void 0 ? {} : { agentPreset: meta.agentPreset }
 		};
-		return Session.create(sessionId, seed, header, options?.inheritedEventCount);
+		return Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
 	}
 	/**
 	* Enter a {@link prepare}d session into the store: install the module-private