dsh-plugin-guide 0.3.42 → 0.4.1

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

@@ -1,212 +0,0 @@
-# SessionTelemetryBackend
-
-English | [中文](session-telemetry.zh.md)
-
-The [capture service](../../packages/session/session-telemetry/README.md) owns canonical-event capture, redaction, and handoff cursors. The [feedback backend](../../packages/session/session-telemetry-otel/README.md) authorizes Session prefixes and owns their independent queue, per-request scheduling, and 4,000,000-byte ceiling. No reporting data reaches model requests.
-
-Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
-
-## The logical record
-
-```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
-}
-```
-
-Every canonical [session event](session.md), including each `assistant/message` or `assistant/attempt` with its complete compact stream and every plugin-merged type the seam never heard of, passes through whole as one ordered ledger record. Process-local `agent/assistant-stream` frames do not enter this durable feed. A new fork starts at its child-owned suffix, including the inherited marker and fork closers; restored Sessions start after their stored prefix, including restored forks. The backend can select `includeHistory` to include the complete prefix; re-adopting the same object resumes after its handoff cursor. Delivery is best-effort: the cursor marks handed-off, not delivered, and records can be lost (crash, reload window) or duplicated (new-object replay, SDK retries), so receivers dedupe ledger records on `(session.id, session.format_version, event.seq)`; ops records deliberately omit that identity — they are signals to alert on, not entries to sum, and tolerate duplicates instead.
-
-## The sharing disclosure
-
-Every backend exposes its deployment-selected mode through the required abstract `sharing` member on `ctx.sessionTelemetry` ([Service Definition README](../../packages/session/session-telemetry/README.md#the-sharing-disclosure)). This is neither a per-Session admission decision nor a delivery receipt. The `/feedback` acknowledgement does not consult it.
-
-```ts type-equiv
-/**
- * Deployment-selected session-sharing mode, not confirmation of SDK delivery.
- */
-type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
-```
-
-## Capture policy
-
-```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` permits stored and inherited records but does not itself authorize capture. The [OTel backend](../../packages/session/session-telemetry-otel/README.md) uses on-demand capture and requires new own explicit feedback; it releases only the complete prefix through that feedback, for every provider.
-
-## The backend contract
-
-```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`, [signatures](#ctxsessiontelemetry--sessiontelemetrybackend-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `SessionTelemetryCoordinator` in its constructor to install the capture side.
-
-## The redact waterfall: `session-telemetry/record`
-
-Every record passes the `session-telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between the canonical-event copy and `emit()` ([event entry](#session-telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
-
-<!-- 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="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/references/official-docs/docs/subsystems/session-telemetry.zh.md

@@ -1,212 +0,0 @@
-# 遥测（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/references/official-docs/docs/subsystems/session-title.i18n.yaml

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for session-title.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/session-title.md
-/session-titles:
-  en: 40ede027d4f62b35
-  zh: 0efd7cb0710a0ed9
-/session-titles/durable-title-state:
-  en: c6be2d86647daa6f
-  zh: fb259d9fb4738f39
-/session-titles/auxiliary-request-record:
-  en: e5d5045ddfa7e771
-  zh: 8c989ef59853cce4
-/session-titles/provider-input-and-output:
-  en: 28ee84e62db773f0
-  zh: 93beca6fbcd02c4e

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

@@ -1,213 +0,0 @@
-# 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 -->