dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/extra/subsystems/session-telemetry.zh.md

@@ -0,0 +1,212 @@
+# 遥测（telemetry）
+
+[English](session-telemetry.md) | 中文
+
+[捕获服务](../../packages/session/session-telemetry/README.zh.md) 负责规范事件捕获、脱敏和交接游标。[反馈后端](../../packages/session/session-telemetry-otel/README.zh.md) 授权 Session 前缀，并负责独立队列、逐请求调度及 4,000,000 字节上限。上报数据不会进入模型请求。
+
+源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
+
+## 逻辑记录
+
+```ts type-equiv
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (the tool message's `isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `session-telemetry/record` policies and
+ * backends.
+ */
+type SessionTelemetrySeverity = 'info' | 'warn' | 'error'
+```
+
+```ts type-equiv
+/**
+ * One logical record handed to a backend — the capture contract's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+interface SessionTelemetryRecord {
+  /** Canonical envelope without data; body carries the separately redacted payload. Absent for operational records. */
+  sourceEvent?: { sessionId: SessionId; envelope: Omit<SessionEvent, 'data'> }
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link SessionTelemetrySeverity}. */
+  severity: SessionTelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `session.format_version`, `event.type`, `event.seq`, plus optional
+   * `session.cwd` / `session.parent_id`; a seeded Session also carries
+   * `session.seed_length` from its exact inherited event count;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+```
+
+每条权威[会话事件](session.zh.md)都会完整透传为一条有序 ledger 记录，包括每个携带完整紧凑 stream 的 `assistant/message` 或 `assistant/attempt`，以及该 seam 从未听说过、由插件合并进来的类型。进程本地 `agent/assistant-stream` frame 不进入该持久 feed。新 fork 从子会话自有后缀开始，包括继承标记和 fork 结束事件；恢复的 Session 从已存储前缀之后开始，包括恢复的 fork。后端可以选择 `includeHistory` 来包含完整前缀；重新收养同一对象时会从 handoff 游标之后继续。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（新对象回放、SDK 重试），因此接收端对 ledger 记录基于 `(session.id, session.format_version, event.seq)` 去重；ops 记录刻意省略这类标识——它们是用于告警的信号，而非用于累加的条目，重复被容忍而非被去重。
+
+## 共享披露
+
+每个后端都通过 `ctx.sessionTelemetry` 上必需的抽象 `sharing` 成员暴露其部署级模式（[Service Definition README](../../packages/session/session-telemetry/README.zh.md#the-sharing-disclosure)）。它既不是逐 Session 的接纳决定，也不是投递回执。`/feedback` 确认文本不查询它。
+
+```ts type-equiv
+/**
+ * Deployment-selected session-sharing mode, not confirmation of SDK delivery.
+ */
+type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
+```
+
+## 捕获策略
+
+```ts type-equiv
+/** Whether capture follows live events or reads the canonical log only when requested. */
+type SessionTelemetryCapture = 'live' | 'on-demand'
+```
+
+```ts type-equiv
+/** Backend-selected capture mode and history policy. */
+interface SessionTelemetryCaptureOptions {
+  /** Follow live events, or wait for explicit capture; defaults to live. */
+  capture?: SessionTelemetryCapture
+  /** Include inherited fork history and stored history from earlier lifecycles; defaults to false. */
+  includeHistory?: boolean
+}
+```
+
+`includeHistory` 允许捕获存储与继承的记录，但本身不授权捕获。[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)使用按需捕获，并要求新的自身显式反馈；它只释放截至该反馈的完整前缀，适用于所有提供方。
+
+## 后端约定
+
+```ts type-equiv
+/**
+ * The minimum backend contract the coordinator requires. {@link SessionTelemetryBackend} is
+ * its service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+interface SessionTelemetrySink {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: SessionTelemetryRecord): void
+  /**
+   * Optional hint that a turn ended. A backend may forward it to its SDK's
+   * flush so records are exported after each turn. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend leaves it unimplemented for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+```
+
+`SessionTelemetryBackend`（`ctx.sessionTelemetry`，[签名](#ctxsessiontelemetry--sessiontelemetrybackend-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `SessionTelemetryCoordinator`，以此装配捕获侧。
+
+## 脱敏 waterfall：`session-telemetry/record`
+
+每条记录在权威事件副本与 `emit()` 之间都要经过 `session-telemetry/record` [waterfall](../cordis-primer.zh.md#cordis-waterfall-semantics)（[事件条目](#session-telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+
+<!-- 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="ctxsessiontelemetry--sessiontelemetrybackend-abstract-seam"></a>
+
+### `ctx.sessionTelemetry` — `SessionTelemetryBackend` (abstract seam)
+
+Loadable form of the backend contract: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a SessionTelemetryCoordinator in its constructor to install the capture side.
+
+```ts cordis-catalog
+/**
+ * See {@link SessionTelemetrySink.emit} — that declaration is the contract's one home.
+ * @param record - the logical record to report; owned by the backend after the call.
+ */
+abstract emit(record: SessionTelemetryRecord): void
+
+/** See {@link SessionTelemetrySink.flush}. */
+flush?(): void
+
+/**
+ * See {@link SessionTelemetrySink.shutdown}.
+ * @returns resolves when the backend's pipeline has quiesced.
+ */
+abstract shutdown(): Promise<void>
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
+
+<a id="session-telemetry-events"></a>
+
+### `session-telemetry/*` events
+
+<a id="session-telemetryrecord--waterfall"></a>
+
+#### `session-telemetry/record` — waterfall
+
+Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+
+```ts cordis-catalog
+/**
+ * Transform one outbound record before it reaches the backend. This
+ * waterfall is the Service Definition's redaction extension point. It ships NO rules
+ * of its own: the
+ * innermost `next()` passes the record through unchanged, and with no
+ * listener mounted records reach the backend as captured, so exported
+ * data is exactly as clean as the rules a deployment mounts. Listeners
+ * stack by transforming `next()`'s return value; returning without
+ * `next()` replaces everything beneath. Dispatched synchronously on the
+ * capture hot path inside the coordinator's containment: a throwing
+ * listener withholds that one record (fail-closed) and never reaches the
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
+ * @param record - the candidate record, already the coordinator's own deep
+ *   copy; listeners return a (possibly new) record and must not mutate it.
+ * @mode waterfall
+ */
+'session-telemetry/record'(record: SessionTelemetryRecord, next: () => SessionTelemetryRecord): SessionTelemetryRecord
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/session-title.md

@@ -0,0 +1,213 @@
+# Session Titles
+
+English | [中文](session-title.zh.md)
+
+Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session/session-title). The shared execution module owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
+
+Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts), [`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
+
+## Durable title state
+
+`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` lists the exact human-message seqs used for the title, while `SessionTitleSnapshot` adds the durable event envelope facts returned by `ctx.sessionTitle.get()` and `foldSessionTitle()`. The `title` projection keeps its version-1 state and client view as only the title string or `null`, so existing persisted cache rows remain readable.
+
+```ts type-equiv
+/** Identifies one session-title provider registration. */
+type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
+```
+
+```ts type-equiv
+/** Exact auxiliary model route that produced a title. */
+interface SessionTitleModelIdentity {
+  /** Registered LLM provider route. */
+  readonly provider: string
+  /** Provider model id. */
+  readonly model: string
+}
+```
+
+```ts type-equiv
+/** Durable ownership record for an accepted session title. */
+type SessionTitleSource =
+  | { readonly kind: 'fallback' }
+  | {
+    readonly kind: 'provider'
+    readonly provider: SessionTitleProviderId
+    readonly model?: SessionTitleModelIdentity
+  }
+  | {
+    /** Explicit user rename: pins the title — automatic generation stops scheduling. */
+    readonly kind: 'user'
+  }
+```
+
+```ts type-equiv
+/** Payload of the log-only `session/title` event. */
+interface SessionTitleEventData {
+  /** Normalized non-empty title text. */
+  readonly title: string
+  /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
+  readonly messageSeqs: SessionSeq[]
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
+  readonly source: SessionTitleSource
+}
+```
+
+```ts type-equiv
+/** Latest folded title plus the title event's durable envelope facts. */
+interface SessionTitleSnapshot extends SessionTitleEventData {
+  /** Seq of the latest `session/title` event. */
+  readonly eventSeq: SessionSeq
+  /** Timestamp of the latest `session/title` event. */
+  readonly updatedAt: number
+}
+```
+
+## Auxiliary request record
+
+The shared execution module records each validated, dispatchable title request before calling the model. The payload reproduces the model-visible system and message input, routing, output limit, resolved reasoning effort, provider ownership, and source-message attribution even when generation later fails.
+
+```ts type-equiv
+/** Exact model-visible request recorded before one auxiliary title dispatch. */
+interface SessionTitleLlmRequestEventData {
+  /** Registered title-provider identity responsible for the request. */
+  readonly titleProvider: SessionTitleProviderId
+  /** Exact human `user/message` seqs represented in `messages`. */
+  readonly messageSeqs: SessionSeq[]
+  /** Exact auxiliary LLM route. */
+  readonly route: SessionTitleModelIdentity
+  /** Exact auxiliary system prompt. */
+  readonly system: string
+  /** Exact auxiliary message list. */
+  readonly messages: Message[]
+  /** Exact auxiliary output-token cap. */
+  readonly maxTokens: number
+  /** Resolved reasoning effort when recorded; older requests can omit it. */
+  readonly reasoningEffort?: ReasoningEffortId
+}
+```
+
+## Provider input and output
+
+The service snapshots eligible messages through one revision and, immediately before each provider call, the latest accepted title including the fallback it just ensured. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends the title with its source-message seqs and source kind.
+
+```ts type-equiv
+/** One eligible human text message exposed to title providers. */
+interface SessionTitleUserMessage {
+  /** Source `user/message` event seq. */
+  readonly seq: SessionSeq
+  /** Exact concatenated text-block content. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/** Automatic generation cadence owned by a registered provider. */
+type SessionTitleAutomaticMode = 'first-prompt' | 'all-prompts'
+```
+
+```ts type-equiv
+/** Immutable input supplied to one title-provider call. */
+interface SessionTitleProviderRequest {
+  /** Live session being titled. */
+  readonly session: Session
+  /** All eligible human messages through this generation revision. */
+  readonly messages: readonly SessionTitleUserMessage[]
+  /** Exact current logged main-request route, when one has been recorded. */
+  readonly route?: SessionTitleModelIdentity
+  /**
+   * Latest accepted title captured at invocation, including an accepted
+   * fallback whose event may follow the last eligible message. Absent before
+   * any title is accepted. The provider decides whether and how to use it.
+   */
+  readonly currentTitle?: SessionTitleSnapshot
+  /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */
+  readonly signal: AbortSignal
+}
+```
+
+```ts type-equiv
+/** Provider output before service-owned normalization and log acceptance. */
+interface SessionTitleProviderResult {
+  /** Proposed title text. */
+  readonly title: string
+  /** Exact seqs from `request.messages` used by this result. */
+  readonly messageSeqs: readonly SessionSeq[]
+  /** Auxiliary LLM route, when generation used a model. */
+  readonly model?: SessionTitleModelIdentity
+}
+```
+
+```ts type-equiv
+/** One optional asynchronous title implementation registered with the service. */
+interface SessionTitleProvider {
+  /** Stable id of the provider recorded with the title. */
+  readonly id: SessionTitleProviderId
+  /** When new human prompts start automatic generation. */
+  readonly automatic: SessionTitleAutomaticMode
+  /**
+   * Produce one title revision.
+   * @param request - message snapshot, current title, current route, session, and cancellation.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
+   */
+  generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
+}
+```
+
+<!-- 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.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work; a replacement may register once disposal has started, and the
+ * closing provider's late results never commit.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/session-title.zh.md

@@ -0,0 +1,213 @@
+# 会话标题
+
+[English](session-title.md) | 中文
+
+[`@deepseek-ai/dsh-session-title`](../../packages/session/session-title) 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享执行模块负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的[持久化日志事件目录](../persistence-catalog.zh.md)负责完整的事件声明。
+
+源码：[`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)、[`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
+
+## 持久标题状态
+
+提供方生成修订时会记录 `SessionTitleProviderId`。`SessionTitleEventData` 列出生成标题时使用的精确人类消息 seq，`SessionTitleSnapshot` 则加入 `ctx.sessionTitle.get()` 与 `foldSessionTitle()` 返回的持久事件封装信息。`title` 投影的版本 1 状态与客户端视图都只保留标题字符串或 `null`，因此既有持久化缓存行仍可读取。
+
+```ts type-equiv
+/** Identifies one session-title provider registration. */
+type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
+```
+
+```ts type-equiv
+/** Exact auxiliary model route that produced a title. */
+interface SessionTitleModelIdentity {
+  /** Registered LLM provider route. */
+  readonly provider: string
+  /** Provider model id. */
+  readonly model: string
+}
+```
+
+```ts type-equiv
+/** Durable ownership record for an accepted session title. */
+type SessionTitleSource =
+  | { readonly kind: 'fallback' }
+  | {
+    readonly kind: 'provider'
+    readonly provider: SessionTitleProviderId
+    readonly model?: SessionTitleModelIdentity
+  }
+  | {
+    /** Explicit user rename: pins the title — automatic generation stops scheduling. */
+    readonly kind: 'user'
+  }
+```
+
+```ts type-equiv
+/** Payload of the log-only `session/title` event. */
+interface SessionTitleEventData {
+  /** Normalized non-empty title text. */
+  readonly title: string
+  /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
+  readonly messageSeqs: SessionSeq[]
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
+  readonly source: SessionTitleSource
+}
+```
+
+```ts type-equiv
+/** Latest folded title plus the title event's durable envelope facts. */
+interface SessionTitleSnapshot extends SessionTitleEventData {
+  /** Seq of the latest `session/title` event. */
+  readonly eventSeq: SessionSeq
+  /** Timestamp of the latest `session/title` event. */
+  readonly updatedAt: number
+}
+```
+
+## 辅助请求记录
+
+共享执行模块会在调用模型前，记录每一项已经过验证且可分发的标题请求。即使后续生成失败，载荷仍会复现模型可见的系统输入与消息输入、路由、输出上限、解析后的推理强度、提供方归属和源消息归因。
+
+```ts type-equiv
+/** Exact model-visible request recorded before one auxiliary title dispatch. */
+interface SessionTitleLlmRequestEventData {
+  /** Registered title-provider identity responsible for the request. */
+  readonly titleProvider: SessionTitleProviderId
+  /** Exact human `user/message` seqs represented in `messages`. */
+  readonly messageSeqs: SessionSeq[]
+  /** Exact auxiliary LLM route. */
+  readonly route: SessionTitleModelIdentity
+  /** Exact auxiliary system prompt. */
+  readonly system: string
+  /** Exact auxiliary message list. */
+  readonly messages: Message[]
+  /** Exact auxiliary output-token cap. */
+  readonly maxTokens: number
+  /** Resolved reasoning effort when recorded; older requests can omit it. */
+  readonly reasoningEffort?: ReasoningEffortId
+}
+```
+
+## 提供方输入与输出
+
+服务会对截至某一修订的合格消息、以及在每次提供方调用前刚刚确保的回退和最新已接纳标题创建快照。提供方返回的 seq 仅可来自该请求；由服务负责的接纳流程会验证顺序、规范化标题、强制执行字节上限，并追加标题及其来源消息 seq 和来源类型。
+
+```ts type-equiv
+/** One eligible human text message exposed to title providers. */
+interface SessionTitleUserMessage {
+  /** Source `user/message` event seq. */
+  readonly seq: SessionSeq
+  /** Exact concatenated text-block content. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/** Automatic generation cadence owned by a registered provider. */
+type SessionTitleAutomaticMode = 'first-prompt' | 'all-prompts'
+```
+
+```ts type-equiv
+/** Immutable input supplied to one title-provider call. */
+interface SessionTitleProviderRequest {
+  /** Live session being titled. */
+  readonly session: Session
+  /** All eligible human messages through this generation revision. */
+  readonly messages: readonly SessionTitleUserMessage[]
+  /** Exact current logged main-request route, when one has been recorded. */
+  readonly route?: SessionTitleModelIdentity
+  /**
+   * Latest accepted title captured at invocation, including an accepted
+   * fallback whose event may follow the last eligible message. Absent before
+   * any title is accepted. The provider decides whether and how to use it.
+   */
+  readonly currentTitle?: SessionTitleSnapshot
+  /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */
+  readonly signal: AbortSignal
+}
+```
+
+```ts type-equiv
+/** Provider output before service-owned normalization and log acceptance. */
+interface SessionTitleProviderResult {
+  /** Proposed title text. */
+  readonly title: string
+  /** Exact seqs from `request.messages` used by this result. */
+  readonly messageSeqs: readonly SessionSeq[]
+  /** Auxiliary LLM route, when generation used a model. */
+  readonly model?: SessionTitleModelIdentity
+}
+```
+
+```ts type-equiv
+/** One optional asynchronous title implementation registered with the service. */
+interface SessionTitleProvider {
+  /** Stable id of the provider recorded with the title. */
+  readonly id: SessionTitleProviderId
+  /** When new human prompts start automatic generation. */
+  readonly automatic: SessionTitleAutomaticMode
+  /**
+   * Produce one title revision.
+   * @param request - message snapshot, current title, current route, session, and cancellation.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
+   */
+  generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
+}
+```
+
+<!-- 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="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work; a replacement may register once disposal has started, and the
+ * closing provider's late results never commit.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.zh.md)
+
+Source: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->