dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/subsystems/session.zh.md

@@ -1,1343 +0,0 @@
-# 会话
-
-[English](session.md) | 中文
-
-[dsh-session](../../packages/core/session) 的内存事件溯源模型。`Session` 是一份由类型化 `SessionEvent` 组成的**仅追加日志**，是 agent（智能体）完整交互历史的唯一真源。LLM（大语言模型）消息历史从日志*派生*而来，从不单独存储；回放即从同一组事件重新派生。日志如何实现**持久化**（持久化 seam、后端、崩溃恢复）是兄弟文档 [persistence.md](persistence.zh.md) 的关注点。
-
-源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
-
-## `SessionEventMap`：事件词汇
-
-仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.zh.md) 添加了 `compaction/start` / `compaction/summary` / `compaction/end`，`@deepseek-ai/dsh-hook-protocol` 为钩子桥接添加了仅记录日志的 `hook/invoked` / `hook/result` 记录。与 `compaction/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.zh.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。
-
-```ts type-equiv
-/** A user-role specialization of the shared message representation. */
-interface UserMessage extends MessageBase {
-  readonly role: 'user'
-}
-```
-
-```ts type-equiv
-/**
- * The merge-extensible, append-only source of truth for an agent interaction.
- * Message history is derived from this log. Every event is lossless JSON and
- * sequence numbers stay contiguous. Assistant attempt events embed their exact
- * compact raw streams so persistence stores one durable settlement per attempt.
- */
-interface SessionEventMap {
-  /**
-   * Opens turn `turn` before the loop claims queued input or runs pre-step.
-   * Rejection, empty input, cancellation, or failure may close it with no
-   * step; otherwise the following identified `user/message` event or batch
-   * records the messages entering the step.
-   */
-  'turn/start': { turn: number }
-  /**
-   * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn
-   * with no entered step has no `step/start` or `step/end`. The loop does not await a
-   * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the
-   * per-request durability checkpoint, and consumers that read storage after
-   * `whenIdle()` flush themselves. Success commits the turn; rejection is
-   * reported live and does not prevent later work.
-   */
-  'turn/end': { turn: number; reason: TurnEndReason }
-  /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
-  'step/start': { turn: number; step: number }
-  /** Closes step `step` of turn `turn`. */
-  'step/end': { turn: number; step: number }
-  /**
-   * A user-role message on the model-visible surface: a direct human prompt
-   * (the queued message claimed for this turn), a synthetic `agent.inject()`
-   * context (file-change notices, subdir AGENTS.md, skill content, cron
-   * notifications, …), or an entered goal continuation round. All three
-   * project their `content` verbatim; `source` tells them apart.
-   */
-  'user/message': UserMessage
-  /** An incremental agent session change admitted at the named turn and step. */
-  'developer/message': {
-    turn: number
-    step: number
-    message: DeveloperMessage
-    /** Earlier request/header defining every tool addition; required exactly when additions are present. */
-    headerSeq?: SessionSeq
-  }
-  /**
-   * The rendered system prompt on the model-visible surface. The loop appends
-   * the first one as surface node 0 before the step's first `user/message`.
-   * A prepared in-history route can append nonempty changes in a continuing
-   * series. An incapable route or new series normalizes text to the first system
-   * node. Normalization empties nonempty later nodes, then rewrites the head if
-   * needed, through logged per-node replacements. An empty rendering always
-   * clears all active system nodes, leaving no older instructions model-visible.
-   * Empty later nodes are dormant and project to no message; an empty head with
-   * no active later node records "no system prompt". Restored nonempty text follows
-   * the same route and series rule; empty nodes never restore older text.
-   */
-  'system/message': { turn: number; step: number; message: SystemMessage }
-  /**
-   * Assembled assistant message for one step (derived history uses this).
-   * Carries the step's `usage` when the adapter reported token accounting, so
-   * the model output and its accounting travel together (there is no separate
-   * usage record). `usage` is absent when the adapter reported none. A turn
-   * cancelled mid-stream finalizes its delivered text/reasoning prefix as this
-   * event with `interrupted: true`; undispatched tool calls are absent. The
-   * marker distinguishes that prefix without re-deriving interruption from turn
-   * boundaries. An aborted turn with no such event streamed no visible content.
-   */
-  'assistant/message': {
-    turn: number
-    step: number
-    message: AssistantMessage
-    /** Exact timed model stream, compacted without joining delta boundaries. */
-    stream: AssistantStreamRecord[]
-    usage?: TokenUsage
-    interrupted?: true
-  }
-  /**
-   * One model attempt that committed no surface message. The embedded stream
-   * preserves a failed, retried, cancelled, or stream-error attempt that
-   * reached settlement without fabricating model-visible history.
-   */
-  'assistant/attempt': { turn: number; step: number; stream: AssistantStreamRecord[] }
-  /**
-   * The model requested one tool invocation: `name` with the raw `arguments`
-   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
-   * call with its `tool/result`.
-   */
-  'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string }
-  /**
-   * A completed tool call's model-facing result, optional internal failure
-   * identity and user-facing reason, and optional tool-private `meta`
-   * presentation payload. The reason remains outside the model-facing message.
-   * `meta` is
-   * opaque to the core (the producing tool owns its shape and reads it back in
-   * `presentResult`) but MUST be JSON-serializable: `Session.append`
-   * runtime-validates all event data with `isJsonValue`, so a non-serializable
-   * `meta` is rejected at the source, and the durable log reproduces the
-   * identical card on replay. Absent
-   * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time
-   * contextual diff here).
-   */
-  'tool/result': {
-    turn: number
-    step: number
-    message: ToolResultMessage
-    /**
-     * Optional failure identity and raw user-facing reason, outside model content;
-     * allowed only when the message has `isError: true`.
-     */
-    error?: { name: string; code: string; reason?: string }
-    meta?: JsonValue
-  }
-  /**
-   * Full header for the next request, appended inside its step before dispatch.
-   * It is log-only; the latest snapshot reconstructs the request header.
-   */
-  'request/header': {
-    header: EpochHeader
-    reason: RequestHeaderReason
-    /** This request begins a distinct model-message series, independently of the header reason. */
-    startsSeries?: true
-  }
-  /**
-   * Route metadata for the next request, logged only when the route, capacity,
-   * or system prompt update mode changes. It does not participate in request
-   * reconstruction or header equality. Prompt admission uses the bound prepared
-   * call's capability, not this snapshot from an earlier request.
-   */
-  'request/context': RequestContext
-  /**
-   * Separates inherited or restored history from later lifecycle-owned work.
-   * This log-only marker need not be at {@link Session.firstLiveSeq}: a fork
-   * seed can already contain its tagged marker and child-owned synthetic
-   * closers before construction.
-   *
-   * A fresh fork child owns one `{ inherited: true }` marker at its exact
-   * inherited-prefix cut, even when that prefix ends in an ancestor marker.
-   * `buildForkSeed` appends that marker before any synthetic closers; the
-   * `Session` constructor supplies it when given only the inherited prefix.
-   * The last tagged marker is the current Session's cut; untagged markers
-   * keep ordinary restore and replay lifecycle boundaries.
-   *
-   * Only the `Session` constructor and `buildForkSeed` may create this marker.
-   * Session append does not reject other writers, so a plugin appending one
-   * would silently classify every live bracket before it as seed history.
-   *
-   * An owner of a standalone open/close bracket (`compaction/start` …
-   * `compaction/end`) reads it because seed history and live work are otherwise
-   * byte-identical: an unmatched opening marker before this event belongs to
-   * an ended lifecycle, whatever ended it. NOT a liveness signal about other
-   * writers — a concurrently live session holds its own boundary elsewhere,
-   * so tolerating concurrent writers needs a signal beyond the log.
-   */
-  'session/end-seed': { inherited?: true }
-}
-```
-
-`UserMessage` 是普通提示词、注入上下文、steering（中途引导）与实时收件箱事件共享的带标识且冻结的 user-role 值。事件包装层只会增加事件本地的位置或结果事实；条目待处理期间，loop 只额外附加驱动器自有的路由状态。
-
-<a id="the-request-header-event-requestheader"></a>
-
-### 请求头事件：`request/header`
-
-请求信封（即 `EpochHeader`：调用配置 + 适配器所提供默认值的标记 + 已组装的工具 schema）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。渲染后的系统提示词不属于请求头：它是派生历史，即 surface 第 0 号节点上的 `system/message` 事件以及任何后续的历史内系统节点（[决策](../../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.zh.md)），因此提示词变更替换或追加一个系统节点，而请求头保持不变。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；请求变化时会追加 reason 为 `'change'` 的快照；未变的信封显式开启消息序列或跟随 surface 替换时，会追加 reason 为 `'series'` 的快照。如果 `'initial'`、`'resume'` 或 `'change'` 快照所属请求同时开启序列，它会携带 `startsSeries: true`；reason `'series'` 已记录这一事实。普通的仅追加后续 Turn，以及同一模型消息序列内的后续 Step 与重试沿用最新快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
-
-```ts type-equiv
-/**
- * Logged request state outside derived history: call config and tools. The
- * system prompt is derived history — surface node 0, a `system/message` event.
- * The latest full `request/header` snapshot reconstructs the header; canonical
- * empty optional fields are absent.
- */
-interface EpochHeader {
-  /** The conversation's call configuration (provider, model, reasoning effort, and sampling scalars). */
-  config: LlmCallConfig
-  /** Effective config fields materialized from the exact adapter rather than proposed by a caller. */
-  adapterDefaults?: LlmCallConfigAdapterDefaults
-  /** Assembled tool schemas; absent for a tool-less request. */
-  tools?: ToolSchema[]
-  /** Retired request text; system prompts belong to system/message events.
-   * @persistenceReserved
-   */
-  system?: never
-}
-```
-
-当前事件接纳要求 `request/header.header` 为规范形式：禁止任何 `system` 字段，必须省略 `tools: []` 与 `adapterDefaults: {}`。仅含空白的系统消息内容、`config.stop: []` 与嵌套扩展保持不变。seed、append 与当前持久化读取拒绝非规范 header，而不会静默规范化；[V3 信封决策](../../.agents/notes/implemented/architecture/2026-09-06-v3-canonical-session-envelopes.zh.md)负责历史转换。包含旧版 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会被拒绝，而不会以不完整方式回放。
-
-### 路由容量事件：`request/context`
-
-请求所解析到的路由的上下文元数据是独立的已记录状态，在同一步骤内紧随 `request/header` 追加，且仅在提供方、模型、容量或 `systemPromptUpdate` 模式与上一条记录不同时追加。它保持在 `EpochHeader` 之外，因为该类型是 `headerEquals` 逐字段比较的重建约定。容量与更新模式描述的是路由，不是请求输入，把它们折叠进去会让一次路由变化被登记为请求信封的 `change`，也会把适配器元数据拉进 loop 的请求重建。与 `request/header` 一样，它不是 `SurfaceEventType`，也不产生 LLM 消息。`session.requestContext()` 以增量方式归并最新一条记录；agent loop 在决定变化后的系统提示词是替换最新的系统节点还是追加到已缓存历史之后时，读取该记录的 `systemPromptUpdate`（[决策规则](../../packages/core/agent-loop/README.zh.md#understand-the-implementation)）。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，因此新记录可以清除较早路由的容量；未声明更新模式的路由同样会清除较早路由的 `systemPromptUpdate`。
-
-```ts type-equiv
-/** Registration-bound metadata for one resolved model route. */
-interface RequestContext {
-  /** Registered provider route the metadata belongs to. */
-  provider: string
-  /** Provider-owned model id the metadata belongs to. */
-  model: string
-  /** Maximum combined request and response context in tokens, when advertised. */
-  contextWindow?: number
-  /** `'in-history'` when the route reads the latest `system` message at any position as the effective system prompt. */
-  systemPromptUpdate?: SystemPromptUpdate
-}
-```
-
-## `SessionEvent<T>`：一条日志条目
-
-基于 `type` 的真正可辨识联合（而非独立的 `type`/`data` 联合），因此 `switch (event.type)` 能直接收窄 `event.data`，无需类型断言。`seq` 是日志中的单调递增位置（`seq = log.length`）；`time` 为 epoch 毫秒。
-
-```ts type-equiv
-/** Sequence number of one existing event in a Session log. */
-type SessionSeq = BrandedNumber<'SessionSeq'>
-```
-
-```ts type-equiv
-/** A Session log gap, prefix length, or read offset, which may equal the event count. */
-type SessionLogOffset = BrandedNumber<'SessionLogOffset'>
-```
-
-```ts type-equiv
-/** Inclusive Session event watermark, or `-1` before any event exists. */
-type SessionSeqCursor = SessionSeq | -1
-```
-
-```ts type-equiv
-/** One existing Session event position, or explicit absence. */
-type OptionalSessionSeq = SessionSeq | null
-```
-
-`SessionSeq(value)` 与 `SessionLogOffset(value)` 只接纳非负安全整数，并拒绝负零。它们仅添加编译期品牌，不改变序列化后的数值；算术会返回普通 `number`，调用方必须按结果的预期角色通过对应构造器重新接纳。
-
-```ts type-equiv
-/**
- * One immutable entry in the session log.
- *
- * A proper discriminated union over `type` (not independent `type`/`data`
- * unions), so `switch (event.type)` narrows `event.data` without casts.
- *
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`system/message`, `user/message`,
- * `assistant/message`, `tool/result`).
- * Non-surface events (boundary markers, attempts, errors) never carry
- * surface metadata — the compiler enforces this at `Session.append()`
- * call sites.
- */
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K
-    /** Monotonic sequence number within the session. */
-    seq: SessionSeq
-    /** Unix epoch milliseconds. */
-    time: number
-    data: SessionEventMap[K]
-    /**
-     * Marks an event a reader may safely skip when it does not recognize
-     * `type`. Absent means required: a reader meeting an unrecognized type
-     * without this marker MUST refuse to reconstruct the session instead of
-     * silently dropping the event, because an unrecognized required event may
-     * change how the rest of the log is interpreted. A writer sets `true` only
-     * on purely informational records whose loss cannot affect reconstruction;
-     * defaulting to required means a forgotten marker over-refuses (an
-     * inconvenience) rather than silently resuming a gutted session.
-     */
-    ignorable?: true
-  } & (K extends SurfaceEventType ? SurfaceIntent<K> : {
-    surfaceOp?: never
-    sourceEventSeqs?: never
-  })
-}[T]
-```
-
-`SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
-
-每个 surface 事件都要求 `surfaceOp`；已知仅日志事件禁止两个 surface 元数据字段。原生未知或已退役的可忽略信封保持不透明。`assistant/message` 嵌入其提供方 stream，并禁止 `sourceEventSeqs`。System、user 与 tool surface 事件可以在来源归属或替换覆盖需要时引用完整、非空且唯一的较早事件集合。`tool/result` 仅在消息带有 `isError: true` 时可以携带 `data.error`；失败结果的失败身份仍可省略。
-
-<a id="surface-types"></a>
-
-## Surface 类型
-
-产生消息的类型（`SurfaceEventType`：`system/message`、`developer/message`、`user/message`、`assistant/message`、`tool/result`）携带 surface 元数据，用来声明它们如何加入有序的派生 surface。`system/message` 承载渲染后的系统提示词：循环把第一条追加为 surface 第 0 号节点，并在提示词变化时恰好替换最新的系统节点，或在历史内路由上追加一条新的；surface 折叠拒绝任何其他覆盖第 0 号节点 `system/message` 的替换，而后续系统节点是普通历史，压缩替换可以遮蔽它。见 [session surface Agent Note](../../.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md)。
-
-### `SurfaceEventType`：事件类型中产生消息的子集
-
-```ts type-equiv
-/**
- * The subset of {@link SessionEventType} values whose events produce LLM
- * messages and are eligible to appear on the ordered surface. Only these
- * event types may carry {@link SurfaceOp}; system, user, and tool events may also cite
- * earlier sources through {@link SessionEvent.sourceEventSeqs}.
- */
-type SurfaceEventType =
-  | 'system/message'
-  | 'developer/message'
-  | 'user/message'
-  | 'assistant/message'
-  | 'tool/result'
-```
-
-### `SurfaceOp`：事件如何进入 surface
-
-```ts type-equiv
-/**
- * How a session event entered the ordered surface. Only valid on
- * {@link SurfaceEventType} events.
- *
- * - `'append'`: added to the tail — normal path for user/assistant/tool
- *   messages.
- * - `{ op: 'replace', startSeq, endSeq }`: replaces surface nodes from `startSeq`
- *   (inclusive) through `endSeq` (inclusive) with this node. Both must exist as
- *   surface nodes in the current surface. `startSeq === endSeq` replaces a single
- *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction; any surface-replacing producer
- *   may use it.
- */
-type SurfaceOp =
-  | 'append'
-  | { op: 'replace'; startSeq: SessionSeq; endSeq: SessionSeq }
-```
-
-`'append'` 是常规的尾部追加路径。`replace` 恰好包含 `op`、`startSeq` 和 `endSeq`，不接受别名或额外键。它遮蔽这两个当前 surface 事件序号之间的闭区间，并在原位置插入新事件；相同端点仅替换一个条目。端点必须早于替换事件，但它们的相对顺序按 surface 顺序而非数值序号顺序确定。
-
-### `SurfaceIntent`：`session.append()` 的参数
-
-```ts type-equiv
-/**
- * Surface placement and cited source-event seqs for {@link Session.append}. Required on
- * message-producing events and forbidden on log-only events.
- */
-type SurfaceIntent<T extends SurfaceEventType = SurfaceEventType> = {
-  surfaceOp: SurfaceOp
-} & (T extends 'assistant/message' ? {
-  /** Assistant messages embed their provider stream instead of citing source events. */
-  sourceEventSeqs?: never
-} : {
-  /** Complete non-empty set of known earlier source-event seqs. */
-  sourceEventSeqs?: SessionSeq[]
-})
-```
-
-对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的 transcript（文本记录）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.zh.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。
-
-`assistant/message` 不能携带 `sourceEventSeqs`；它的 `stream` 拥有精确 provider 证据。其他 surface event 不引用较早 event 时省略该字段，需要引用时使用完整非空 list。
-
-<a id="plugin-owned-message-projections"></a>
-### 插件拥有的消息投影
-
-修改内容的插件用 `@messageProjection` 标记事件声明，并通过 `ctx.sessions.registerMessageProjection()` 注册纯处理器。Session 在提交前通过处理器校验完整决策，应用其不可变消息更新，并推进 `contentGeneration`。缺少处理器时拒绝操作，包括恢复和独立折叠，卸载已经使用的处理器后也会拒绝读取缓存。独立读取器将处理器显式传给 `foldSurface(events, projections)`，并通过 `deriveEventMessage()` 应用 `projectedMessages`。当前格式目录为离线读取器装配第一方处理器。[图片省略插件](compaction.zh.md#image-offload)拥有图片专用的事件及解释逻辑。
-
-```ts type-equiv
-/** Readonly history immediately before a message-projection event. */
-interface SessionMessageProjectionContext {
-  /** Current message-producing event sequences in model-visible order. */
-  nodes: readonly SessionSeq[]
-  /** Contiguous event window; entries at or beyond the candidate seq are not committed inputs. */
-  events: readonly SessionEvent[]
-  /** Absolute sequence of the window's first event. */
-  baseSeq: SessionLogOffset
-  /** Previously projected messages keyed by their original event sequences. */
-  messages: ReadonlyMap<SessionSeq, Message>
-}
-```
-
-```ts type-equiv
-/** Pure interpretation of one plugin-owned event that changes existing message content. */
-interface SessionMessageProjection<T extends SessionEventType = SessionEventType> {
-  /** Event interpreted by this definition; declare it with `@messageProjection` in SessionEventMap. */
-  type: T
-  /**
-   * Validate the complete durable decision before returning any updates. Preserve
-   * message identities and publish immutable copies without mutating the input.
-   * @param event - candidate event, not yet applied to the supplied history.
-   * @param context - history preceding this decision.
-   * @returns changed current messages keyed by their original sequences.
-   * @throws when the durable decision cannot be applied to this history.
-   */
-  project(event: SessionEvent<T>, context: SessionMessageProjectionContext): ReadonlyMap<SessionSeq, Message>
-}
-```
-
-### `SessionSurface`：实时只读 surface 投影
-
-`Session.surface` 返回会话稳定的 `SessionSurface` 视图。同一个增量管理器在提交前校验追加候选事件，并根据已提交事件推进该投影；调用方可以观察成员关系和替换代次，但不能调用校验。
-
-`SurfaceManager(log, baseSeq?, projections?)` 也可以折叠一个连续的已加载窗口，其第一个事件的绝对序号为 `baseSeq`。每个事件在该绝对序号空间中仍保持连续；如果替换跨过窗口头部，由于其声明的范围并不存在，该替换会失败。
-
-```ts type-equiv
-/** Readonly live projection of the message-producing session events. */
-interface SessionSurface {
-  /** Current surface event sequences in model-visible order. */
-  readonly nodes: readonly SessionSeq[]
-  /** Monotonic count of committed positional replacements. */
-  readonly replaceGeneration: number
-  /** Monotonic count of committed replacements and plugin-owned message changes. */
-  readonly contentGeneration: number
-}
-```
-
-### `SurfaceFoldReplacement` 与 `SurfaceFoldResult`：完整的 surface 回放
-
-`foldSurface(events, projections)` 返回一份独立的当前事件 seq 列表，以及每个声明的替换范围实际遮蔽的 seq。实时管理器复用同一套状态转换，但不保留替换历史。每提交一次替换，其 `replaceGeneration` 就递增一次，使增量消费方能够区分纯尾部增长与重写。
-
-```ts type-equiv
-/** One replacement operation observed while folding a session surface. */
-interface SurfaceFoldReplacement {
-  /** Seq of the event that replaced the prior surface range. */
-  seq: SessionSeq
-  /** Declared inclusive start seq of the replaced surface range. */
-  start: SessionSeq
-  /** Declared inclusive end seq of the replaced surface range. */
-  end: SessionSeq
-  /** Actual surface entries removed by the operation, in surface order. */
-  shadowedSeqs: SessionSeq[]
-}
-```
-
-```ts type-equiv
-/** Complete result of replaying the surface operations in a session log. */
-interface SurfaceFoldResult {
-  /** Current surface event sequences in model-visible order. */
-  nodes: SessionSeq[]
-  /** Replacement operations in event order. */
-  replacements: SurfaceFoldReplacement[]
-  /** Immutable projected messages, keyed by their original event sequences. */
-  projectedMessages: ReadonlyMap<SessionSeq, Message>
-}
-```
-
-## `Session` 公共 API
-
-去除方法体的声明与源码中的普通类保持同步，覆盖其脱离态工厂、状态访问器、append 方法和历史投影。存储操作仍由生成的 [`ctx.sessions` 小节](#ctxsessions--sessionstore)记录。
-
-```ts public-api
-/**
- * An event-sourced session: an append-only log of {@link SessionEvent}s.
- *
- * Plain class (not a Service) — create live instances via
- * `ctx.sessions.create()` and detached instances via {@link create}.
- * Seeding with an existing event log replays/forks a session.
- * @typert object
- */
-declare class Session {
-  /** The ordered surface over this session's event log. */
-  get surface(): SessionSurface;
-  /**
-   * Detached, deep-frozen creation metadata (format version, cwd, lineage,
-   * and whether fork history exists). Supplied by the store via `ctx.sessions.create()`. When a
-   * `Session` is created without a store-owned header, a minimal header is
-   * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
-   * `session.header` is always present. Kept out of the event log — it is a
-   * storage concern, not replayable conversation state.
-   */
-  readonly header: SessionHeader;
-  /** Number of leading events inherited from this Session's fork parent. */
-  readonly inheritedEventCount: SessionLogOffset;
-  /** The session identity, derived from its durable header's single copy. */
-  get id(): SessionId;
-  /**
-   * The constructor seed length (0 without one), before any marker appended
-   * during construction. Seed events never publish on `session/event`. A
-   * marker appended before the store attaches occupies this seq without
-   * publishing either; otherwise this seq is available for the next append.
-   *
-   * This in-process offset is not persisted. A fork seed can already contain
-   * the child's inherited marker and synthetic closers, so its child-owned
-   * history starts at {@link inheritedEventCount}, before this offset. A
-   * resumed Session's seed contains its full stored log, while its inherited
-   * count keeps the durable fork cut. Consumers needing complete canonical
-   * history start at seq 0.
-   */
-  readonly firstLiveSeq: SessionLogOffset;
-  /**
-   * First event produced for this object lifecycle. A new fork includes its
-   * child-owned seed marker and closers; a restored Session starts after its
-   * complete stored prefix. This in-process capture offset is not persisted.
-   */
-  readonly firstLifecycleSeq: SessionLogOffset;
-
-  /**
-   * Create a detached session by validating and snapshotting borrowed seed
-   * events and storage metadata.
-   * @param id - session identity.
-   * @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: SessionId,
-    seed?: readonly SessionEvent[],
-    header?: SessionHeader,
-    inheritedEventCount?: SessionLogOffset,
-    projections?: readonly SessionMessageProjection[],
-    ): Session;
-  /**
-   * Restore a detached session by adopting an independently owned or deeply frozen seed.
-   * Runtime-required event fields, event envelopes, sequence continuity, surface
-   * transitions, and header fields are validated without copying or freezing events.
-   * Embedded Assistant streams remain opaque until a stream consumer or storage
-   * verifier reads them.
-   * @param id - restored session identity.
-   * @param seed - independently owned or deeply frozen events.
-   * @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: SessionId,
-    seed: readonly SessionEvent[],
-    header: SessionHeader,
-    inheritedEventCount: SessionLogOffset,
-    eventState: SessionSeedEventState,
-    projections?: readonly SessionMessageProjection[],
-    ): Session;
-  /**
-   * 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.
-   */
-  eventAt(seq: SessionSeq): SessionEvent | undefined;
-  /**
-   * 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.
-   */
-  snapshotEvents(
-    fromSeq: SessionLogOffset = SessionLogOffset(0),
-    toSeqExclusive: SessionLogOffset = this.seq,
-    ): readonly SessionEvent[];
-  /**
-   * 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(): readonly SessionEvent[];
-  /**
-   * Whether one existing event position is outside the fork-inherited prefix.
-   * @param seq - event position in this Session.
-   * @returns true when the event belongs to this Session rather than its parent.
-   */
-  isOwnSeq(seq: SessionSeq): boolean;
-  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
-  get seq(): SessionLogOffset;
-  /**
-   * Append one typed event to the log and synchronously notify observers via
-   * the store-owned, module-private publication hooks. The hot path never blocks
-   * on I/O — persistence plugins buffer asynchronously. Once the event enters
-   * the log, the append is committed: observer failures are logged and
-   * contained per listener, so they do not change the return value or prevent
-   * later listeners from observing the same accepted event.
-   *
-   * @param type - The event type (key of {@link SessionEventMap}).
-   * @param data - The event payload; must be JSON-serializable.
-   * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
-   *   events this one derives from. REQUIRED for
-   *   {@link SurfaceEventType} events (every message-producing event must
-   *   declare how it joins the surface, the sole source of derived model
-   *   history) and
-   *   rejected by the compiler for non-surface types like `turn/start` or
-   *   `assistant/attempt`. Assistant messages embed their exact provider
-   *   stream and cannot cite top-level source events.
-   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
-   *   `data` that entered the log, so reading `event.data` back sees the logged
-   *   value, never the caller's still-mutable input.
-   * @throws if `data` or surface metadata is not losslessly JSON-serializable
-   *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
-   *   circular reference, sparse array, or an exotic object such as
-   *   Map/Set/Date/class instance), or when the candidate violates the
-   *   request-header empty-field or tool-error consistency rules, or the
-   *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier source-event references, positional replacement validity, and complete
-   *   shadowed-node coverage). One iterative pass reads, validates, and
-   *   copies each nested value once, so a stateful getter cannot supply one value
-   *   to validation and another to storage. The event log is the durable source
-   *   of truth, so a bad event fails at the append site rather than later during
-   *   a backend flush. A synchronous internal dispatch validation failure or an
-   *   append reentered while this acceptance/publication boundary is open also
-   *   rejects before the log changes.
-   */
-  append<T extends SessionEventType>(
-    type: T,
-    data: SessionEventMap[T],
-    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []
-    ): SessionEvent<T>;
-  /**
-   * The {@link EpochHeader} in force after the log's last header event — the
-   * header the NEXT request will be compared against — or undefined before
-   * the first `request/header` snapshot. The live, incrementally-maintained
-   * form of `foldRequestHeader(session.snapshotEvents())`: each header event is folded
-   * once, when first seen, so a per-step read costs O(new events).
-   * @returns the folded header, or undefined when no header event exists yet.
-   */
-  requestHeader(): EpochHeader | undefined;
-  /**
-   * Return the latest resolved route metadata, or `undefined` before the first
-   * `request/context` event. Each event is folded once.
-   * @returns the latest immutable route metadata.
-   */
-  requestContext(): RequestContext | undefined;
-  /**
-   * Fold unseen committed events into capability-independent tool history.
-   * Initial access reconstructs inherited history; later reads consume only new events.
-   * @returns an immutable snapshot for LLM request projection, including historical addition definitions.
-   */
-  toolHistory(): ToolHistory;
-  /**
-   * Derive the LLM message history by walking the ordered sequences of
-   * message-producing events maintained by `surfaceOp` markers. The
-   * surface is the single source of derived history: every message-producing
-   * 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}, with logged message projections applied
-   * without changing node membership or message identity.
-   *
-   * 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**.
-   * 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(): Message[];
-  /**
-   * 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: SessionEvent): Message | null;
-}
-```
-
-## 派生历史：`deriveMessages()` 与 `deriveEventMessage()`
-
-`Session.deriveMessages()` 将事件日志投影为模型看到的 `Message[]`。它是缓存的（每个 surface 节点在首次出现时投影一次；surface 重写触发重建）且冻结的（每次调用返回一个新数组，引用共享的深冻结消息，因此通过投影修改已记录的历史在类型上不可表达）。`deriveEventMessage(event)` 是折叠所应用的逐节点纯函数，公开暴露以便外部重建器能以完全相同的规则投影日志前缀，不会与缓存产生分歧。投影规则：
-
-- `user/message` → 一条携带确切 `content` 的 user 消息；可选 envelope 仅作为日志中的展示元数据保留。
-- `assistant/message` → 一条 assistant 消息，包含生成它的提供方和模型，以及可选的适配器私有回放状态。其嵌入式紧凑 stream 是回放、usage 与 UI 证据，而不是第二条 message。**内容为空的** `assistant/message` 也会跳过：因 max-tokens 而截断且无内容的步骤仍会记录一条 `assistant/message` 来保存 stream、usage、提供方和模型，但无内容的 assistant 轮次不得进入提供方 transcript（文本记录）。
-- `tool/result` → 一条一等 tool-role 消息，携带结果内容与工具调用标识。
-- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；其类型化 source 标明生产方，并携带所有生产方专用数据。
-
-其余所有事件（`turn/*`、`step/*`、`assistant/attempt`、插件所属的 `llm/retry`）均为结构信息，不会投影为消息。token 记账会展开每个 `assistant/message` 或 `assistant/attempt` 的嵌入式 stream，message 顶层 `usage` 存在时仍是已提交 message 的权威。失败的模型请求 attempt 因此可以保留提供方 usage，而无需虚构 assistant message。当前逻辑校验会拒绝没有提供方／模型的 request header 和 assistant 消息，而不会猜测路由；受支持的历史表示会在当前 Session 存在前，由其相邻格式迁移边归一化并校验。
-
-## 活跃会话 fork API
-
-`ctx.sessions.create(id, { seed, meta })` 是底层的回放/fork 原语。对于普通的活跃会话 fork，`SessionStore` 暴露一个策略 API：
-
-- `fork(source, boundary?, childSessionId?)` 接受一个活跃的 `Session` 对象或活跃的 `SessionId`，选取到 `SessionSeq` boundary（含）为止的源事件（默认为当前最后一个事件），要求所选前缀结束时没有开放轮次，然后创建一个活跃的子会话，包含深克隆的 seed event、`parentSession`、`isSeeded: true`、精确 `inheritedEventCount` 及继承的 `cwd`。
-
-显式 `boundary` 允许调用者从任意稳定的轮次间位置 fork，包括之前的 `turn/end` 或更晚的独立纯日志事件，即使源会话有更新的事件或正在进行的轮次。API 拒绝结束于开放轮次内的前缀，而不是静默截断。`dsh-subagent-fork-in-process` 保留其已完成前缀截断逻辑，因为工具调用时的委托通常在父轮次仍然打开时启动；普通的会话分支应显式指定请求的 boundary。
-
-<a id="why-a-turn-ended-turnendreasonmap"></a>
-
-## 轮次的结束原因：`TurnEndReasonMap`
-
-`turn/start` 没有 trigger 字段。已进入的 `user/message` 批次记录进入每个步骤的内容，`llm/retry` 记录请求恢复，idle 注入则保持待处理，直到唤醒交付抵达后续 pre-step。实时轮次会保留停止驱动器的类型化 [`AgentCancelCause`](core.zh.md#the-agent-handle)；只有在导入受支持的粗粒度取消记录且记录未保存调用方时，持久化才使用额外的 `{ kind: 'legacy' }` 原因。
-
-```ts type-equiv
-/** Durable cancellation cause, including imports whose original coarse record carried no cause. */
-type TurnEndCancelCause = AgentCancelCause | { readonly kind: 'legacy' }
-```
-
-```ts type-equiv
-/**
- * Why a turn ended. Merge-extensible sum type.
- */
-interface TurnEndReasonMap {
-  completed: { kind: 'completed' }
-  /** A cancellation request interrupted the live turn. */
-  aborted: { kind: 'aborted'; reason: TurnEndCancelCause }
-
-  blocked: { kind: 'blocked' }
-  /**
-   * The turn failed. `error` is always a structured failure: the `LlmError`
-   * facts verbatim, or `{ message: errorChain(error), code: 'UNKNOWN' }`
-   * flattened from any other error.
-   */
-  error: { kind: 'error'; error: LlmFailure }
-  /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
-  'max-tokens': { kind: 'max-tokens' }
-  /**
-   * A crash-orphaned turn was closed after the fact: agent-loop resume appends
-   * this closer for a stored log whose last turn never ended, and session-query
-   * synthesizes it on cold reads. The loop never emits this marker live, and
-   * the events recorded before the crash remain intact.
-   */
-  interrupted: { kind: 'interrupted' }
-  /**
-   * Fork-seed construction closed a turn that was still open at the fork
-   * boundary in the source session. Only fork seeds carry this marker — the
-   * loop never emits it — and the source events before the boundary remain
-   * intact in the child.
-   */
-  forked: { kind: 'forked' }
-}
-```
-
-`max-tokens` 与模型调用中同名的 `FinishReason` 对应：只要轮次内有任何步骤以 `max-tokens` 结束，整个轮次就以 `max-tokens` 而不是 `completed` 结束（即使之后继续执行，截断事实仍优先），让消费方能够区分正常停止和截断停止。取消和错误仍是不同的结果。loop 不会实时发出 `interrupted` 或 `forked`：崩溃恢复合成 `interrupted`（见 [persistence.md](persistence.zh.md)），而 fork 种子构造合成 `forked`。该 map 可通过合并扩展。
-
-## 执行封闭与独立事件
-
-一个轮次包围一次模型循环执行，而不是整个会话日志。AgentLoop 只会在轮次内进入 pre-step 批次时记录注入的 `user/message` 事件；插件所属的纯日志事件仍可出现在 `turn/end` 与下一个 `turn/start` 之间，占用事件 seq 但不递增轮次编号。持久化会将每个连续且已接受的事件纳入有界持久化批次，而崩溃修复只关闭确实仍处于开放状态的尾部轮次。需要即时持久性屏障的生产方会显式等待 `ctx.sessions.flush(session)`。
-
-可合并扩展事件的关系由声明它的插件拥有，因此核心不会仅因没有开放轮次就拒绝未知事件。见[独立事件决策](../../.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md)。
-
-## 种子结束边界：`session/end-seed`
-
-`buildForkSeed` 在精确的 inherited-prefix cut 追加 `session/end-seed { inherited: true }`，然后添加合成的 fork 结束事件。`Session` constructor 保留该预先构造的 marker，或在 seed 仅含 inherited prefix 时追加 marker。restore 保留 tagged marker，并且只在完整 stored seed 尚未以 marker 结尾时追加普通 `session/end-seed {}`。两种形式都只进入 log 且不产生 message；只有 constructor 和 `buildForkSeed` 可以创建它们。
-
-对于 fork lineage，定位 payload 携带 `inherited: true` 的最后一个 marker；当前格式 decoding 只在 `SessionHeader.isSeeded` 为 true 时要求该 marker，并从其 seq 推导 `inheritedEventCount`。对于 lifecycle ownership，定位任一形式的最后一个 `session/end-seed`。重新打开已经以任一 marker 结尾的 seed 时，不会再追加普通 marker。
-
-它之所以必要，是因为种子历史与实时工作在字节层面完全相同，这会让任何拥有独立开／闭括号的插件失效：一个未配对的 `compaction/start`，无论写入方是在压缩中途崩溃、还是此刻正在压缩，读起来都一样。在 `session/end-seed` 之前的开启标记来自构造种子，并且属于一个已结束的生命周期，无论结束原因为何（崩溃、进程接替，或从仍在运行的父会话 fork 出来），因此其所有方可以视之为已死。这只覆盖*本*会话继承的括号：另一个并发存活的会话可能在同一段历史上持有开放括号，而它自己的边界在别处，因此容忍并发写入方还需要日志之外的存活信号。核心写入该边界但不从中读取任何内容——括号的词汇表仍归其所属插件，这也正是崩溃修复只关闭轮次／步骤／工具边界而从不处理 `compaction/*` 的原因。
-
-按真人活动排序 Session 的消费方会排除该边界：接手 Session 不算工作，因此按日志尾部排序会把每个打开过的 Session 顶到最前。
-
-## 插件贡献的仅日志事件
-
-插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间。生成的[持久化日志事件目录](../persistence-catalog.zh.md)会列出每个核心或插件贡献的事件；压缩 seam 的 `compaction/*` 语义在 [compaction.md](compaction.zh.md) 中讨论。
-
-如果同一个插件事件族中的多条事件要组装成一个 Web Client Conversation Node，该事件族中的每条 start、update、result、resource 或 interruption 事件都必须携带或独立推导出同一个稳定业务 id。此要求只约束需要关联的 Node 事件族，并不要求每条 Session 事件都有业务 id；Client 因此无须根据相邻关系猜测归属，也无须扫描历史。参见 [Conversation 子系统](conversation.zh.md)。
-
-钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次。
-
-### 插件记录
-
-实验性包在 `PluginRecordMap` 中声明插件自有的状态：`appendPluginRecord()` 根据每项声明约束名称与 payload 类型，并在 `plugin:` 命名空间中追加一条带 `ignorable: true` 标记的事件。`pluginRecordOf()` 读取已存记录，其 payload 为未知类型，不受当前声明约束。[实验性持久化目录](../experimental-persistence-catalog.zh.md)列出当前声明。调用方限制、保留方式与读取路径见[包 README](../../packages/core/session/README.zh.md#write-experimental-plugin-records)。
-
-```ts type-equiv
-/**
- * Event type of an experimental plugin record: `plugin:` followed by
- * slash-separated segments of lowercase letters, digits, `.`, `_`, and `-`,
- * each starting with a letter or digit. A record type is never a
- * {@link SessionEventMap} member.
- */
-type PluginRecordType = `plugin:${string}`
-```
-
-```ts type-equiv
-/**
- * Payloads written by experimental packages, keyed by their `plugin:` record
- * names. Packages augment this map to type writes and enter the current plugin
- * record catalog; these declarations do not enter {@link SessionEventMap} or
- * released persistence schemas. Stored records still require owner validation.
- */
-interface PluginRecordMap {}
-```
-
-```ts type-equiv
-/**
- * One committed experimental plugin record, read from the log by
- * `pluginRecordOf`. The record's owner validates `data` before use, because a
- * restored record carries whatever JSON an earlier build of its owner wrote,
- * or a V3 event that a format migration renamed into the `plugin:` namespace held.
- */
-interface PluginRecord {
-  /** The record type, chosen by the owning plugin. */
-  readonly type: PluginRecordType
-  /** The record's position in the Session log. */
-  readonly seq: SessionSeq
-  /** Unix epoch milliseconds at append. */
-  readonly time: number
-  /** The JSON payload as committed. */
-  readonly data: unknown
-}
-```
-
-## 持久性约定
-
-持久化后端依赖的约定如下：持久日志无损保存每个事件，每个 Assistant attempt 都是一个 `assistant/message` 或 `assistant/attempt`，其嵌入式紧凑 stream 会保留原始带时间 chunk。`seq` 在这些 settlement 与所有交错事件之间保持连续。后端可以为事件批次选择自己的存储 framing，只要句柄的 `read()` 返回与追加时完全一致的事件即可；当前 JSONL 每个事件写一行（见 [persistence.md](persistence.zh.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.snapshotEvents()` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
-
-消费此约定的后端见 [persistence.md](persistence.zh.md)。
-
-## Remote 目录与 workspace 打开
-
-`ModelCatalog` 是 `session/modelCatalog` 返回的 Host generation 模型目录：它携带部署默认值、可路由 provider id、成功的 provider 分组与相互隔离的 provider 失败。它不由某个 Session 派生，因此与 Session projection 分开保存。
-
-`SessionOpenWorkspacePathRequest` 携带绝对路径或已按 workspace 解析的 `path`。`SessionOpenWorkspacePathValue` 确认 Host 已接受原生交接。Session-aware Client 会在已知当前 Session cwd 时据此解析相对路径；controller 将路径原样交给打开器，并通过 Session Remote 错误词汇表报告无效请求、取消与打开器失败。 可选的 `action: "reveal"` 选择文件管理器导航；省略时使用默认应用打开。
-
-可选的 `application` 指定文件关联应用，不修改系统默认值；`workspacePathApplications({ path })` 在校验 Host 路径后返回当前关联应用、名称、图标和默认项。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxsessioncontroller--sessioncontroller"></a>
-
-### `ctx.sessionController` — `SessionController`
-
-Host service backing the generated `ctx.remote.session` namespace.
-
-```ts cordis-catalog
-/**
- * Resolve or resume one ordinary Session for another Host API domain.
- * @param sessionId - Session identity whose Agent owns the operation.
- * @returns the live Agent or the stable Session-domain failure.
- */
-resolveAgent(sessionId: SessionId): Promise<ApiSessionAgentResult>
-
-/**
- * Inspect one attached or persisted Session without activating its Agent.
- * @param sessionId - durable Session identity.
- * @param signal - optional caller cancellation for persistence reads.
- * @returns the current attached state or persisted header and event prefix.
- */
-inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionInspection>
-
-/**
- * Read all visible Session rows without resuming an Agent.
- * @param _request - reserved empty list request.
- * @param signal - cancellation for persistence reads and summary generation.
- * @returns visible Session summaries ordered by activity.
- */
-@Remote('list') async list(_request: SessionListRequest, signal: AbortSignal): Promise<SessionListValue>
-
-/**
- * Search visible Session content without resuming an Agent. A non-owner
- * receives only the hits whose Session `allows()` admits; `hasMore`
- * describes the bounded result before that filtering.
- * @param request - literal message-content query.
- * @param signal - cancellation for list and search reads.
- * @returns authorized bounded Session search results.
- */
-@Remote('search') async search(request: SessionSearchRequest, signal: AbortSignal): Promise<SessionSearchValue>
-
-/**
- * Create one ordinary Session for a new conversation, reusing the named blank Session while it is reusable.
- * @param request - optional blank Session to reuse, location, and Agent preset.
- * @returns the created or reused Session identity and its preset when configured.
- */
-@Remote('create') create(request: SessionCreateRequest): Promise<SessionCreateValue>
-
-/**
- * Select one Session-local model after explicitly resuming the Session; save the default in the background.
- * @param request - Session identity and requested model selection.
- * @returns the normalized selection installed for the Session, without waiting for default persistence.
- */
-@Remote('selectModel') selectModel(request: SessionSelectModelRequest): Promise<SessionSelectModelValue>
-
-/**
- * Select the first available account model after login when no provider API key is configured.
- * @returns after saving the first available model or retaining the existing default.
- */
-@Remote async initializeDefaultModel(): Promise<void>
-
-/**
- * Describe every currently routable model for Host-generation selectors.
- * @returns provider-grouped models, the deployment default, and isolated provider failures.
- */
-@Remote('modelCatalog') modelCatalog(): Promise<ModelCatalog>
-
-/**
- * Report whether this deployment can hand a Session workspace path to a native desktop.
- * @returns true when the matching open operation is available.
- */
-@Remote canOpenWorkspacePath(): boolean
-
-/**
- * Describe the serving desktop for authenticated file-action routes.
- * @returns Host name, configured availability, and platform-specific file-manager behavior.
- */
-workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' | 'explorer' | 'directory' | null }
-
-/**
- * Verify one path through the composed filesystem and open it on the Host desktop.
- * @param request - path after best-effort Session workspace resolution.
- * @param signal - caller lifetime; abort terminates the native command.
- * @returns confirmation after the native opener accepts the path.
- * @throws RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.
- */
-@Remote('openWorkspacePath') async openWorkspacePath( request: SessionOpenWorkspacePathRequest, signal: AbortSignal, ): Promise<SessionOpenWorkspacePathValue>
-
-/**
- * Query current file handlers on the serving desktop without activating an Agent.
- * @param request - file path in Host filesystem syntax.
- * @param signal - caller lifetime, propagated to filesystem and desktop queries.
- * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
- * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
- */
-@Remote('workspacePathApplications') async workspacePathApplications( request: { readonly path: string }, signal: AbortSignal, ): Promise<readonly SessionWorkspacePathApplication[]>
-
-/**
- * Rename one Session after explicitly resuming it.
- * @param request - Session identity and proposed title.
- * @returns the accepted title and durable event sequence.
- */
-@Remote('rename') rename(request: SessionRenameRequest): Promise<SessionRenameValue>
-
-/**
- * Fork one cold-readable exact event prefix into a new Session. An omitted
- * boundary selects the latest completed-turn prefix; an open cut receives
- * synthetic fork closers.
- * @param request - source Session, optional exact inclusive event boundary, and migration preflight choice.
- * @returns the new Session identity.
- */
-@Remote('fork') async fork(request: SessionForkRequest): Promise<SessionForkValue>
-
-/**
- * Admit one prompt after explicitly resuming its Session.
- * @param request - Session identity, prompt content, source metadata, and delivery mode.
- * @param signal - caller cancellation before prompt admission begins.
- * @returns acknowledgement that the Agent accepted the prompt.
- */
-@Remote('prompt') async prompt(request: SessionPromptRequest, signal: AbortSignal): Promise<SessionPromptValue>
-
-/**
- * Read one image proven reachable from the addressed Session log.
- * @param request - Session and attachment identities used for authorization.
- * @returns the durable attachment reference and base64-encoded bytes.
- */
-@Remote('attachment') attachment(request: SessionAttachmentRequest): Promise<SessionAttachmentValue>
-
-/**
- * Mutate one still-pending queue occurrence, resuming a cold Agent first.
- * @param request - Session, queue item, and requested mutation.
- * @returns acknowledgement that the queue mutation was applied.
- */
-@Remote('updateQueue') updateQueue(request: SessionUpdateQueueRequest): Promise<SessionUpdateQueueValue>
-
-/**
- * Cancel one active Agent turn without dropping its pending inbox.
- * @param request - Session whose active Agent turn is cancelled.
- * @returns acknowledgement that cancellation was requested.
- */
-@Remote('cancel') cancel(request: SessionCancelRequest): SessionCancelValue
-
-/**
- * Read one cold-safe, message-aligned Session history page.
- * @param request - durable address, backward cursor, and page budget.
- * @param signal - cancellation for persistence reads.
- * @returns one chronological page.
- */
-@Remote({ name: 'page', resources: { session: addressedSession } }) page(request: SessionPageRequest, signal: AbortSignal): Promise<SessionPage>
-
-/**
- * Follow one Session log from its opening or resume cursor.
- * @param request - durable address and last committed sequence already held by the caller.
- * @param signal - cancellation owned by the Remote stream carrier.
- * @returns a complete opening snapshot followed by gap-free durable event
- *   frames and optional cursorless assistant-stream frames.
- */
-@Remote({ mode: 'stream', resources: { session: addressedSession } }) follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>
-
-/**
- * Read exact projections, returning cached hints only when migration is required.
- * @param request - Session whose current values are required.
- * @param signal - cancellation for the Session read.
- * @returns a sequenced baseline, cached hints when migration is deferred, or null when absent.
- */
-@Remote('projections') async projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise<SessionProjectionsValue>
-
-/**
- * Stream a complete live-control baseline followed by replacement frames.
- * @param signal - cancellation owned by the Remote stream carrier.
- * @returns one complete baseline followed by live replacement frames.
- */
-@Remote({ mode: 'stream' }) async *control(signal: AbortSignal): AsyncIterable<SessionControlFrame>
-```
-
-Types: [SessionId](core.zh.md) · [SessionInspection](persistence.zh.md) · [SessionSearchRequest](session-query.zh.md)
-
-Source: [`packages/api/session-controller/src/index.ts`](../../packages/api/session-controller/src/index.ts)
-
-<a id="ctxsessions--sessionstore"></a>
-
-### `ctx.sessions` — `SessionStore`
-
-In-memory session store (`ctx.sessions`).
-
-Persistence is intentionally not implemented here — the agent lifecycle attaches a session-log writer to each published session's write handle; a session published outside that lifecycle persists nothing.
-
-```ts cordis-catalog
-/**
- * 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: SessionMessageProjection): () => Promise<void>
-
-/**
- * Create a session owned by the calling fiber: disposing that fiber stops
- * event notification and removes the session from the store. `options.seed`
- * populates the session with a copy of those events (replay/fork);
- * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
- * and parent lineage, and delegation depth) as the immutable
- * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
- *
- * For an agent whose session must be torn down IN ORDER with its loop (so the
- * loop's final events are published before the store attachment ends), do NOT use this
- * — fold the session lifecycle into the agent's own effect via
- * {@link prepare} + {@link enter} + {@link announce} (see
- * `dsh-agent-loop`'s creation transaction).
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header.
- * @returns the live session, already entered and announced.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path (storage backends key directories off it).
- */
-create(id?: SessionId, options?: CreateSessionOptions): Session
-
-/**
- * Build a session WITHOUT entering it into the store — validate the id/cwd and
- * construct the {@link Session} (with its immutable {@link SessionHeader}).
- * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
- * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
- * effect so a fiber unload tears the session + agent down as a single ORDERED
- * chain rather than as racing sibling effects — which would remove the publication hooks
- * before the driver's closing events commit, dropping them.
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header. With
- *   `eventState`, every seed event is either independently owned or any
- *   shared value is deeply frozen; {@link Session.fromRestore} validates and
- *   adopts those values without copying or freezing them.
- * @returns the constructed session, NOT yet in the store.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path.
- */
-prepare(id?: SessionId, options?: PrepareSessionOptions): Session
-
-/**
- * Enter a {@link prepare}d session into the store: install the module-private
- * append publication hooks and add it to the store. Returns the DETACH
- * disposer (hooks + store removal). Does NOT emit `session/created` —
- * the caller yields this disposer inside its effect and THEN calls
- * {@link announce}, so a throwing `session/created` listener rolls the attach
- * back instead of leaking it.
- *
- * Re-checks the id for a duplicate: `prepare` and `enter` are public
- * cross-package primitives and a caller may interleave arbitrary work (or
- * another create) between them, so a stale prepared session must NOT overwrite
- * a live store entry of the same id — its detach disposer would later delete
- * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public API cannot
- * assume that.
- *
- * @param session - a {@link prepare}d session not yet in the store.
- * @returns the detach disposer (publication hooks + store removal). When called from
- *   a synchronous `session/created` listener, removal and disposal wait until
- *   that creation dispatch unwinds.
- * @throws if a session with this id is already in the store.
- */
-enter(session: Session): () => void
-
-/** Emit `session/created` exactly once for an {@link enter}ed session (with
- * the carrier {@link enter} captured). Separate from {@link enter} so the
- * caller can yield the detach disposer first (rollback safety — see
- * {@link enter}).
- * @param session - the entered session to announce to listeners.
- * @throws if the session is not live or its announcement already began,
- *   including a reentrant call from a creation listener. */
-announce(session: Session): void
-
-/**
- * Dispatch the awaited `session/flush` durability checkpoint for `session`,
- * with the carrier captured at {@link enter}. THE flush entry point: the
- * store owns the carrier, so callers (the checkpoint policy's per-request
- * barrier, goal-round-driver's idle checkpoint, teardown drains, and consumers
- * that flush themselves before reading storage) must come through here
- * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner
- * and one spelling.
- * @param session - the session whose buffered events must reach durable storage.
- * @returns whether at least one durability listener participated, after every
- *   listener has settled successfully.
- * @throws the first registered listener failure after every listener settles.
- */
-async flush(session: Session): Promise<boolean>
-
-/**
- * Look up a live session.
- * @param id - the session id to look up.
- * @returns the session, or undefined when no live session has that id.
- */
-get(id: SessionId): Session | undefined
-
-/**
- * All live sessions, in creation order.
- * @returns a fresh array; mutating it does not affect the store.
- */
-list(): Session[]
-
-/**
- * Create a live child session from an exact prefix of a live source.
- * `boundary` is an inclusive source event seq; omitted means the source's
- * current last event. An open tail receives synthetic tool results and
- * step/turn closers with the forked cause. Closed steps and turns remain
- * unchanged, including any failed tool calls already missing results.
- * `inheritedEventCount` counts only copied source events, excluding these closers.
- *
- * @param source - Live source session object or id.
- * @param boundary - Inclusive source event seq to fork through; omitted means
- *   the source's current last event, and omitted on an empty source forks an
- *   empty child.
- * @param childSessionId - Optional child session id; omitted delegates to
- *   `SessionStore`'s id policy.
- * @returns The created live child session.
- */
-fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session
-```
-
-Types: [CreateSessionOptions](persistence.zh.md) · [PrepareSessionOptions](persistence.zh.md) · [SessionId](core.zh.md)
-
-Source: [`packages/core/session/src/index.ts`](../../packages/core/session/src/index.ts)
-
-<a id="api-session-events"></a>
-
-### `api-session/*` events
-
-<a id="api-sessionactivity--emit"></a>
-
-#### `api-session/activity` — emit
-
-One user-authored durable message advanced Session list activity.
-
-```ts cordis-catalog
-/**
- * One user-authored durable message advanced Session list activity.
- * @mode emit
- * @param sessionId - addressed Session identity.
- * @param updatedAt - durable message time used for list ordering.
- */
-'api-session/activity'(sessionId: SessionId, updatedAt: number): void
-```
-
-Types: [SessionId](core.zh.md)
-
-Source: [`packages/api/session-controller/src/types.ts`](../../packages/api/session-controller/src/types.ts)
-
-<a id="api-sessionadded--emit"></a>
-
-#### `api-session/added` — emit
-
-A Session became visible or its Agent was created or disposed. Consumers upsert the summary and replace its current running and availability state.
-
-```ts cordis-catalog
-/**
- * A Session became visible or its Agent was created or disposed.
- * Consumers upsert the summary and replace its current running and availability state.
- * @mode emit
- * @param summary - current list row for the Session.
- */
-'api-session/added'(summary: SessionSummary): void
-```
-
-Source: [`packages/api/session-controller/src/types.ts`](../../packages/api/session-controller/src/types.ts)
-
-<a id="api-sessionerror--emit"></a>
-
-#### `api-session/error` — emit
-
-One Agent failed outside a durable turn position.
-
-```ts cordis-catalog
-/**
- * One Agent failed outside a durable turn position.
- * @mode emit
- * @param sessionId - Agent and Session identity.
- * @param message - user-safe failure chain.
- */
-'api-session/error'(sessionId: SessionId, message: string): void
-```
-
-Types: [SessionId](core.zh.md)
-
-Source: [`packages/api/session-controller/src/types.ts`](../../packages/api/session-controller/src/types.ts)
-
-<a id="api-sessionremoved--emit"></a>
-
-#### `api-session/removed` — emit
-
-A Session left the live Host registry.
-
-```ts cordis-catalog
-/**
- * A Session left the live Host registry.
- * @mode emit
- * @param sessionId - removed Session identity.
- */
-'api-session/removed'(sessionId: SessionId): void
-```
-
-Types: [SessionId](core.zh.md)
-
-Source: [`packages/api/session-controller/src/types.ts`](../../packages/api/session-controller/src/types.ts)
-
-<a id="api-sessionstatus--emit"></a>
-
-#### `api-session/status` — emit
-
-One Agent changed running state.
-
-```ts cordis-catalog
-/**
- * One Agent changed running state.
- * @mode emit
- * @param sessionId - Agent and Session identity.
- * @param running - whether the Agent is running.
- */
-'api-session/status'(sessionId: SessionId, running: boolean): void
-```
-
-Types: [SessionId](core.zh.md)
-
-Source: [`packages/api/session-controller/src/types.ts`](../../packages/api/session-controller/src/types.ts)
-
-<a id="session-events"></a>
-
-### `session/*` events
-
-<a id="sessioncreated--emit"></a>
-
-#### `session/created` — emit
-
-Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Creation announcement during session publication. A synchronous throw vetoes and rolls
- * back with a paired disposal; detach requested during dispatch is deferred.
- * A returned-promise rejection is logged but cannot retroactively veto this
- * synchronous boundary.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only sessions entered through that agent's context.
- * @param session - the session just entered and announced.
- * @mode emit
- */
-'session/created'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/core/session/src/index.ts`](../../packages/core/session/src/index.ts)
-
-<a id="sessiondisposed--emit"></a>
-
-#### `session/disposed` — emit
-
-Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
-
-```ts cordis-catalog
-/**
- * Emitted once when an announced session leaves the store, including
- * publication rollback, but never for an entry whose creation announcement
- * did not begin. Listener failures are logged and contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
- * @param session - the session that is no longer live in the store.
- * @mode emit
- */
-'session/disposed'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/core/session/src/index.ts`](../../packages/core/session/src/index.ts)
-
-<a id="sessionevent--emit"></a>
-
-#### `session/event` — emit
-
-Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Post-commit, fire-and-forget append feed. The listener snapshot resolves
- * before the log push, but callbacks run after it; observer failures are
- * logged and contained without making the committed append fail.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only events from sessions entered through that agent's context.
- * @param session - the session whose log grew.
- * @param event - the appended event, exactly as recorded.
- * @mode emit
- */
-'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/core/session/src/index.ts`](../../packages/core/session/src/index.ts)
-
-<a id="sessionflush--parallel"></a>
-
-#### `session/flush` — parallel
-
-Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
-
-```ts cordis-catalog
-/**
- * Awaited parallel durability checkpoint: every listener runs and the
- * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
- * @param session - the session whose buffered events must reach durable storage.
- * @mode parallel
- */
-'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/core/session/src/index.ts`](../../packages/core/session/src/index.ts)
-<!-- END GENERATED cordis-surface -->