docs(session-title): record contracts and generated catalogs

.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-21-log-backed-session-titles.md: a2cef52bf88f03eef804e3d7f2bf83288ba49b2e
+2026-07-21-log-backed-session-titles.zh.md: ea6ecc6e66d1afac772cdd93936c6ed49d5409a2

.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md

@@ -0,0 +1,60 @@
+# Agent Note: Log-backed session titles
+
+Status: implemented
+
+English | [中文](2026-07-21-log-backed-session-titles.zh.md)
+
+## Problem
+
+A session needs a short human-facing title before an editor, terminal, or query consumer can present it usefully. The cheapest implementation can derive one from the first prompt, while higher-quality implementations may call a model over the first prompt or the whole conversation. Those strategies have different latency, cost, routing, and retry behavior, but every consumer needs one durable source of truth.
+
+Session identity metadata is immutable, the event log is the replay and fork boundary, and every event must remain turn-enclosed. A model-generated title often finishes after the main turn closes, so writing it synchronously would delay the agent response while writing it as mutable metadata would bypass ordinary persistence, replay, and lineage semantics. Concurrent prompts, provider HMR, cancellation, and ignored abort signals also make an unfenced background result capable of overwriting a newer title.
+
+## Decision
+
+The [`session-title` capability family](../../../../packages/session-title/README.md) owns title state and generation policy. `@deepseek-ai/dsh-session-title` provides `ctx.sessionTitle`, a deterministic first-message fallback, and a registry for at most one optional asynchronous provider. `@deepseek-ai/dsh-session-title-llm` owns the common auxiliary-model request policy; separate first-message and all-user-messages plugins choose input cadence. The shared agent spine mounts only the fallback service with explicit example limits, leaving both model providers opt-in.
+
+### Event ownership and folding
+
+Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either fallback provenance or the registered provider id plus optional provider/model route. `foldSessionTitle()` selects the latest event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Title events never enter `session.surface` or `deriveMessages()`.
+
+The core session package exposes `ctx.sessions.appendOutOfBand()` only for plugin event types whose owners also declaration-merge an `OutOfBandSessionEventMap` marker. An open turn receives the log-only event directly and owns its normal checkpoint. A closed log receives `turn/start → event → turn/end` under the plugin's trigger, followed by an awaited flush. Once the synthetic turn opens, target-append failure still attempts to close and flush it; detach is deferred until the sequence settles. Session titles contribute the `session-title` zero-step trigger and opt `session/title` into this seam.
+
+### Input and asynchronous timing
+
+Only text blocks from human-source `user/message` events are eligible. Empty, control-only, and non-text prompts wait for the next eligible message. The service schedules the first fallback without awaiting it from the prompt path, normalizes whitespace and control sequences, applies the configured word and UTF-8 byte limits without splitting a code point, and records the first message seq.
+
+Automatic provider work waits until the corresponding `request/header` records the main request's exact provider/model route, then runs independently of the agent response. A completion joins whichever turn is open at acceptance time or uses the zero-step append path. Explicit `refresh(session, signal?)` materializes any missing fallback and awaits the registered provider; without a provider it returns the fallback.
+
+The first-message provider schedules once when a fresh session first creates its fallback. An automatic failure does not reschedule on later prompts; `refresh()` is the retry path. The all-messages provider schedules after every eligible human prompt and passes all eligible messages through that revision, including seeded history. Its newer revision aborts and supersedes older pending or active work.
+
+### Registration, routing, and failure policy
+
+`register(provider)` validates one branded stable id, cadence, and generation function, then returns an effect disposer. A second live registration throws immediately. Provider disposal and session disposal abort pending and active work. Every session-local generation has a monotonic revision and exact registration identity; acceptance rechecks revision, registration, session liveness, and cancellation, so a provider that ignores its abort signal cannot commit stale output.
+
+Model providers require explicit word, CJK-character, input-byte, output-token, and timeout limits. Optional `provider` and `model` overrides are a pair; without them the helper uses the exact route from the logged main request header. Selected messages are framed as JSON under one fixed language-aware instruction. Oversized input is rejected rather than truncated because truncation would make the recorded source seqs falsely imply complete use.
+
+Automatic provider failures are nonfatal warnings and retain the latest title. Explicit refresh failures reject to the caller. Output must be non-empty text with unique ordered seqs drawn from the fixed request; the service normalizes and byte-limits it before durable acceptance.
+
+### Forks and consumers
+
+A fork inherits seed title events unchanged, like the rest of its source log. The first-message provider does not automatically retitle a fork. The all-messages provider may append a child-owned revision after a later child prompt, using inherited and new eligible messages.
+
+`ctx.sessionQuery.readTitle()` folds one live-preferred or persisted log without loading titles during `listSessions()`. ACP maps the event to `session_info_update` during both live streaming and load replay, using the event timestamp for `updatedAt`. The TUI uses the latest title as its header subtitle and sets the terminal window title to `<session title> — <configured product title>` after terminal-safe rendering.
+
+## Alternatives considered
+
+- **Mutable `SessionHeader` or side metadata** — rejected because it creates a second persistence mutation protocol, weakens immutable identity metadata, makes crash atomicity backend-specific, and gives forks ambiguous copy-versus-reference behavior. The append-only log already owns replayable latest-wins state.
+- **Await title generation before returning the agent response** — rejected because auxiliary provider latency and failure would sit on the main interaction's critical path. The deterministic fallback gives immediate useful state while a better title may arrive later.
+- **Put titles in derived history or the request prefix** — rejected because UI metadata would consume tokens, change cache identity, and make the main model observe its own label. A log-only event remains reconstructable without becoming model-visible.
+- **Permit multiple registered providers and resolve precedence after completion** — rejected because completion order is not product precedence and would make retries, HMR, and provenance nondeterministic. A deployment that needs a composite policy can register one provider that owns that policy.
+- **Silently truncate oversized auxiliary input** — rejected because the provider result would claim exact source-message provenance while receiving only partial text. Keeping the prior title and warning preserves truthful attribution.
+- **Index titles in `listSessions()` immediately** — rejected because the existing lightweight metadata list would need per-backend derived-index synchronization. Exact `readTitle()` establishes the read contract without precommitting search or indexing policy.
+
+## Consequences
+
+- Titles survive JSONL and SQLite persistence, replay through ACP, and follow fork inheritance without a separate mutable record.
+- A fallback appears without an auxiliary call; deployments choose whether better titles justify model cost and whether later prompts should retitle a session.
+- Late accepted titles consume event seqs and may create a balanced zero-step turn, so transcript and persistence fixtures expose the update even though model history and KV-cache identity do not change.
+- One provider and monotonic per-session revisions make disposal, supersession, and stale-result rejection explicit, at the cost of leaving multi-strategy precedence to a composite provider.
+- Manual rename, deletion, generated-versus-user precedence, search, and list indexing remain outside the capability.

.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md

@@ -0,0 +1,60 @@
+# Agent Note: 基于日志的会话标题
+
+Status: implemented
+
+[English](2026-07-21-log-backed-session-titles.md) | 中文
+
+## 问题
+
+会话需要一个面向用户的简短标题，编辑器、终端或查询消费方才能有效呈现它。成本最低的实现可以从第一条提示词派生标题，质量更高的实现则可以让模型处理第一条提示词或整个对话。这些策略在延迟、成本、路由和重试行为上各有不同，但所有消费方都需要一个持久的真源。
+
+会话身份元数据不可变，事件日志是回放和 fork 的边界，而且每个事件都必须包围在轮次内。模型生成的标题往往在主轮次结束后才完成，因此同步写入会延迟 agent（智能体）响应，而作为可变元数据写入则会绕过常规的持久化、回放和沿袭语义。并发提示词、提供方 HMR（热模块替换）、取消以及被忽略的中止信号，还可能让未受版本校验约束的后台结果覆盖更新的标题。
+
+## 决策
+
+[`session-title` 功能包族](../../../../packages/session-title/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载带显式示例限制的回退服务，两种模型提供方均需按需启用。
+
+### 事件归属与折叠
+
+每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源信息，或已注册的提供方 id 加可选的提供方和模型路由。`foldSessionTitle()` 选择最新事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。标题事件永远不会进入 `session.surface` 或 `deriveMessages()`。
+
+核心会话包通过 `ctx.sessions.appendOutOfBand()` 暴露这一接口，但只允许所属插件同时通过声明合并向 `OutOfBandSessionEventMap` 添加标记的插件事件类型使用。开放轮次会直接接收纯日志事件，并负责其常规检查点。已关闭的日志会在该插件的触发器下接收 `turn/start → event → turn/end`，随后等待刷写完成。合成轮次一旦开启，即使目标追加失败，系统仍会尝试将其关闭并刷写；整个序列完成前会延迟 detach。会话标题提供 `session-title` 零步骤触发器，并让 `session/title` 使用这一服务边界。
+
+### 输入与异步时序
+
+只有人类来源的 `user/message` 事件中的文本块才符合条件。空提示词、仅含控制字符的提示词和非文本提示词会等待下一条合格消息。服务从提示词路径调度首个回退标题而不等待其完成，随后规范化空白和控制序列，应用已配置的单词数和 UTF-8 字节限制且不拆分代码点，并记录第一条消息的 seq。
+
+自动提供方工作会等待相应的 `request/header` 记录主请求的准确提供方和模型路由，然后独立于 agent 响应运行。完成结果在被接受时加入当时开放的轮次，否则使用零步骤追加路径。显式调用 `refresh(session, signal?)` 会生成尚缺的回退标题并等待已注册的提供方；没有提供方时则返回回退标题。
+
+首消息提供方仅在新会话首次创建回退标题时调度一次。自动执行失败后，后续提示词不会重新调度；`refresh()` 是重试路径。全部消息提供方会在每条合格且由人类发出的提示词后调度，并传入截至该修订的所有合格消息，包括预置历史记录。较新的修订会中止并取代更早的待执行或活跃工作。
+
+### 注册、路由与失败策略
+
+`register(provider)` 会验证一个带品牌类型的稳定 id、执行时机和生成函数，然后返回 effect 资源释放函数。第二个活跃注册会立即抛出错误。提供方和会话执行 dispose（资源释放）时，都会中止待执行和活跃工作。每项会话本地生成都有单调递增的修订号和对应的注册身份；接受结果时会重新检查修订号、注册、会话活跃状态和取消状态，因此即使提供方忽略中止信号，也无法提交陈旧输出。
+
+模型提供方必须显式配置单词数、CJK 字符数、输入字节数、输出 token 数和超时限制。可选的 `provider` 和 `model` 覆盖项必须成对提供；两者均未提供时，辅助组件会使用主请求已记录请求头中的准确路由。系统在一条固定且能区分语言的指令下，将选中的消息封装为 JSON。过大输入会被拒绝而不是截断，因为截断会让记录的源消息 seq 错误地表示这些消息已被完整使用。
+
+自动提供方故障只会发出非致命警告，并保留最新标题。显式刷新失败则会向调用方返回拒绝。输出必须是非空文本，并包含来自固定请求、唯一且有序的 seq；服务会在持久接受前对其进行规范化并施加字节限制。
+
+### Fork 与消费方
+
+与源日志的其他部分相同，fork 会原样继承作为种子的标题事件。首消息提供方不会自动为 fork 重新生成标题。全部消息提供方可以在子会话出现后续提示词后追加一项归子会话所有的修订，并使用继承的合格消息和新增的合格消息。
+
+`ctx.sessionQuery.readTitle()` 会折叠一份实时优先或已持久化的日志，而不会在 `listSessions()` 期间加载标题。ACP（Agent Client Protocol）会在实时流式输出和加载回放期间把该事件映射到 `session_info_update`，并使用事件时间戳作为 `updatedAt`。TUI 使用最新标题作为其标题栏副标题，并在完成终端安全渲染后，将终端窗口标题设置为 `<session title> — <configured product title>`。
+
+## 考虑过的替代方案
+
+- **可变 `SessionHeader` 或独立元数据**：不予采纳，因为这会创建第二套持久化变更协议，削弱不可变身份元数据，让崩溃原子性因后端而异，并使 fork 的复制或引用行为产生歧义。仅追加日志已经负责可回放的后写覆盖状态。
+- **返回 agent 响应前等待标题生成**：不予采纳，因为辅助提供方的延迟和故障会进入主交互的关键路径。确定性回退方案可以立即提供可用状态，质量更高的标题则可稍后到达。
+- **将标题放入派生历史记录或请求前缀**：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
+- **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
+- **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
+- **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取契约，而没有提前锁定搜索或索引策略。
+
+## 后果
+
+- 标题可以在 JSONL 和 SQLite 持久化中存续，通过 ACP 回放，并遵循 fork 继承语义，而无需单独的可变记录。
+- 回退标题无需辅助调用即可出现；部署方可以自行决定更优标题是否值得模型成本，以及后续提示词是否需要重新生成会话标题。
+- 延迟接受的标题会占用事件 seq，并可能创建平衡的零步骤轮次，因此 transcript（文本记录）和持久化 fixture（测试前置数据）会呈现该更新，尽管模型历史和 KV 缓存标识保持不变。
+- 单个提供方和每会话单调递增的修订号让释放、取代和陈旧结果拒绝行为明确可见，但多策略优先级必须由复合提供方负责。
+- 手动重命名、删除、生成标题与用户标题的优先级、搜索和列表索引不在此功能范围内。