dsh-plugin-dev-kb 1.5.2 → 1.8.0

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

@@ -1,224 +0,0 @@
-# Session References
-
-English | [中文](session-reference.zh.md)
-
-Host-backed file discovery plus structured cross-session reference requests and prepared message contexts. The [file-reference contract](../../packages/context/file-reference) owns path-only completion records and grammar; the [session-reference contract](../../packages/context/session-reference) defines canonical URIs, current-surface projection, tag-safe JSON and byte retention, stable errors, and the untrusted model prompt. Host adapters use these types instead of passing their UI mention syntax into the agent core.
-
-Sources: [`packages/context/file-reference/src/types.ts`](../../packages/context/file-reference/src/types.ts) · [`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
-
-## File candidates
-
-`FileReferenceCandidate` is the path-only discovery result. The addressed agent supplies the working-directory scope; providers decide ranking and namespace access without reading file contents.
-
-```ts type-equiv
-/** One path-only completion candidate inside the target session cwd. */
-interface FileReferenceCandidate {
-  /** User-facing path accepted by normal prompts and filesystem tools. */
-  path: string
-  /** Directories keep completion open; files finish the mention. */
-  kind: 'file' | 'directory'
-}
-```
-
-## Inputs and candidates
-
-`SessionReferenceInput` is the host-independent selection. The id is authoritative; the label is display metadata carried into the snapshot.
-
-```ts type-equiv
-/** One source session selected by a host. */
-interface SessionReferenceInput {
-  /** Opaque source session identity. */
-  sessionId: SessionId
-  /** Optional user-facing mention label. */
-  label?: string
-}
-```
-
-`SessionReferenceCandidate` is host-facing discovery output. Its `label` uses the latest Session title when present, while its optional display text prefers a subagent's durable creation label; filtering searches both alongside Session id and cwd, never transcript text. The Remote candidate's canonical mention uses the display text when present.
-
-```ts type-equiv
-/** One host-facing candidate from exact session metadata. */
-interface SessionReferenceCandidate {
-  /** Opaque source session identity. */
-  sessionId: SessionId
-  /** Latest log-backed title, falling back to the opaque session id. */
-  label: string
-  /** Display and canonical-mention text, preferring a subagent's durable creation label over {@link label}. */
-  displayTitle?: string
-  /** Source session working directory, when recorded. */
-  cwd?: string
-  /**
-   * True when {@link SessionReferenceCandidate.cwd} is recorded and equals the
-   * requesting agent's. Hosts that only surface a distinguishing location
-   * read this instead of comparing paths they never received.
-   */
-  sameWorkspace: boolean
-  /** Source session creation time in Unix epoch milliseconds. */
-  createdAt: number
-}
-```
-
-The `sessionReferenceResolver/candidates` Remote method serves the same discovery to browser consumers and attaches each candidate's canonical prompt mention.
-
-```ts type-equiv
-/** One discovery candidate carrying its canonical prompt mention. */
-interface SessionReferenceMentionCandidate extends SessionReferenceCandidate {
-  /** Canonical `@[label](dsh-session:…)` mention serialized into the prompt draft. */
-  mention: string
-}
-```
-
-## Prepared messages
-
-Preparation preserves readable current-message content and returns at most one aggregated context. Its durable source records keep `capturedThroughSeq` as a coordinate in the referenced Session's original generation; they never reinterpret it as a seq in the containing Session. `capturedFormatVersion` records that generation, with absence meaning released format v0.
-
-```ts type-equiv
-/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
-interface SessionReferenceSource {
-  kind: 'session-reference'
-  /** Material lifted out of another session's log (`recall` context form). */
-  form: 'recall'
-  version: 1
-  references: {
-    sessionId: string
-    label: string
-    /** Source Session format generation; absence identifies version 0. */
-    capturedFormatVersion?: number
-    capturedThroughSeq: OptionalSessionSeq
-    compacted: boolean
-    originalMessages: number
-    retainedMessages: number
-    omittedMessages: number
-    omittedBytes: number
-    truncated: boolean
-    inputIndex: number
-  }[]
-}
-```
-
-```ts type-equiv
-/** Direct message content and optional referenced-session context. */
-interface PreparedReferencedMessage {
-  /** Readable message content after host mention tokens are removed. */
-  content: ContentBlock[]
-  /** Aggregated untrusted snapshot, absent when the message has no references. */
-  additionalContext?: UserMessage
-}
-```
-
-## Errors
-
-`SessionReferenceError.code` separates invalid configuration or input, self-reference, count limits, source-read failure, budget failure, and cancellation. Host protocols map these codes to their own error envelopes without inspecting prompt bytes.
-
-```ts type-equiv
-/** Stable failure codes exposed to host adapters. */
-type SessionReferenceErrorCode =
-  | 'SESSION_REFERENCE_INVALID_CONFIG'
-  | 'SESSION_REFERENCE_INVALID_REFERENCE'
-  | 'SESSION_REFERENCE_SELF_REFERENCE'
-  | 'SESSION_REFERENCE_TOO_MANY'
-  | 'SESSION_REFERENCE_READ_FAILED'
-  | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
-  | 'SESSION_REFERENCE_CANCELLED'
-```
-
-<!-- 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="ctxfilereferences--filereferenceservice-abstract-seam"></a>
-
-### `ctx.fileReferences` — `FileReferenceService` (abstract seam)
-
-Host capability for cancellable file-reference discovery.
-
-```ts cordis-catalog
-/**
- * List file and directory candidates for one agent's working directory.
- * @param agent - target agent whose session cwd bounds discovery.
- * @param query - path text following `@` or `@"`.
- * @param signal - caller cancellation.
- * @returns deterministic path-only candidates.
- */
-abstract list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/context/file-reference/src/index.ts`](../../packages/context/file-reference/src/index.ts)
-
-<a id="ctxsessionfilereferences--sessionfilereferences"></a>
-
-### `ctx.sessionFileReferences` — `SessionFileReferences`
-
-Host Remote adapter over the composed file-reference provider.
-
-```ts cordis-catalog
-/**
- * List file and directory candidates for one Agent's working directory.
- * @param agent - target Agent resolved from the Session identity on the wire.
- * @param query - path text following `@` or `@"`.
- * @param signal - caller cancellation.
- * @returns deterministic path-only candidates from the composed provider.
- */
-@Remote list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/api/session-controller/src/file-references.ts`](../../packages/api/session-controller/src/file-references.ts)
-
-<a id="ctxsessionreferenceresolver--sessionreferenceresolver"></a>
-
-### `ctx.sessionReferenceResolver` — `SessionReferenceResolver`
-
-Exact-read consumer that prepares immutable cross-session message context.
-
-```ts cordis-catalog
-/**
- * List reference candidates, ranked by working-directory affinity.
- *
- * Discovery runs at keystroke rate, so titles and subagent labels only ever
- * come from projection reads; sessions without either fall back to their id.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title/display-title substring.
- * @param limit - optional positive result cap.
- * @param signal - optional cancellation boundary for host autocomplete teardown.
- * @returns candidates with canonical mention labels and presentation titles.
- */
-async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
-
-/**
- * Remote face of {@link listCandidates}: the configured candidate limit
- * applies, and every candidate carries the canonical mention a host inserts
- * into the prompt draft.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title substring.
- * @param signal - caller cancellation.
- * @returns mention-carrying candidates in rank order.
- */
-@Remote('candidates') async remoteExportCandidates( agent: Agent, query: string, signal: AbortSignal, ): Promise<SessionReferenceMentionCandidate[]>
-
-/**
- * Snapshot all references for one accepted direct message and return one aggregated durable context.
- * Automatic budgets use the last assembled route, or agent options before any assembly.
- * Missing model capacity or adapter uses 64 KiB; other metadata lookup failures and cancellation reject preparation.
- * Truncated previews include omission facts and a full-snapshot spill locator, or an explicit unavailable notice.
- * Cancellation prevents context publication, including when storage completes after cancellation.
- * @param agent - target agent; references to it are rejected.
- * @param content - already host-normalized readable message content.
- * @param references - structured source sessions in mention order.
- * @param signal - optional cancellation boundary for the active turn.
- * @returns detached content and optional referenced-session context.
- */
-async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
-```
-
-Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
-
-Source: [`packages/context/session-reference/src/index.ts`](../../packages/context/session-reference/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,224 +0,0 @@
-# 会话引用
-
-[English](session-reference.md) | 中文
-
-由 Host 支撑的文件发现，以及结构化的跨会话引用请求与准备后的消息上下文。[文件引用约定](../../packages/context/file-reference)负责仅含路径的补全记录与语法；[会话引用约定](../../packages/context/session-reference)定义规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
-
-来源：[`packages/context/file-reference/src/types.ts`](../../packages/context/file-reference/src/types.ts) · [`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
-
-## 文件候选项
-
-`FileReferenceCandidate` 是仅含路径的发现结果。被寻址的 agent 提供工作目录范围；提供方负责排序和命名空间访问，但不会读取文件内容。
-
-```ts type-equiv
-/** One path-only completion candidate inside the target session cwd. */
-interface FileReferenceCandidate {
-  /** User-facing path accepted by normal prompts and filesystem tools. */
-  path: string
-  /** Directories keep completion open; files finish the mention. */
-  kind: 'file' | 'directory'
-}
-```
-
-## 输入与候选项
-
-`SessionReferenceInput` 是与宿主无关的选择。id 具有权威性；label 是随快照携带的显示元数据。
-
-```ts type-equiv
-/** One source session selected by a host. */
-interface SessionReferenceInput {
-  /** Opaque source session identity. */
-  sessionId: SessionId
-  /** Optional user-facing mention label. */
-  label?: string
-}
-```
-
-`SessionReferenceCandidate` 是面向宿主的发现输出。存在最新 Session 标题时，它的 `label` 使用该标题；可选显示文本则优先使用 subagent 的持久创建 label。筛选会同时搜索两者、Session id 与 cwd，绝不搜索 transcript（文本记录）。Remote 候选在 `displayTitle` 存在时用它标记规范 mention。
-
-```ts type-equiv
-/** One host-facing candidate from exact session metadata. */
-interface SessionReferenceCandidate {
-  /** Opaque source session identity. */
-  sessionId: SessionId
-  /** Latest log-backed title, falling back to the opaque session id. */
-  label: string
-  /** Display and canonical-mention text, preferring a subagent's durable creation label over {@link label}. */
-  displayTitle?: string
-  /** Source session working directory, when recorded. */
-  cwd?: string
-  /**
-   * True when {@link SessionReferenceCandidate.cwd} is recorded and equals the
-   * requesting agent's. Hosts that only surface a distinguishing location
-   * read this instead of comparing paths they never received.
-   */
-  sameWorkspace: boolean
-  /** Source session creation time in Unix epoch milliseconds. */
-  createdAt: number
-}
-```
-
-`sessionReferenceResolver/candidates` Remote 方法向浏览器消费方提供同一发现能力，并为每个候选附上规范提示词 mention。
-
-```ts type-equiv
-/** One discovery candidate carrying its canonical prompt mention. */
-interface SessionReferenceMentionCandidate extends SessionReferenceCandidate {
-  /** Canonical `@[label](dsh-session:…)` mention serialized into the prompt draft. */
-  mention: string
-}
-```
-
-## 准备后的消息
-
-准备过程保留可读的当前消息内容，并最多返回一个聚合上下文。其持久 source 记录会把 `capturedThroughSeq` 保留为被引用 Session 原始 generation 中的坐标，绝不会把它重新解释为所在 Session 的 seq。`capturedFormatVersion` 记录该 generation；缺失表示已发布格式 v0。
-
-```ts type-equiv
-/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
-interface SessionReferenceSource {
-  kind: 'session-reference'
-  /** Material lifted out of another session's log (`recall` context form). */
-  form: 'recall'
-  version: 1
-  references: {
-    sessionId: string
-    label: string
-    /** Source Session format generation; absence identifies version 0. */
-    capturedFormatVersion?: number
-    capturedThroughSeq: OptionalSessionSeq
-    compacted: boolean
-    originalMessages: number
-    retainedMessages: number
-    omittedMessages: number
-    omittedBytes: number
-    truncated: boolean
-    inputIndex: number
-  }[]
-}
-```
-
-```ts type-equiv
-/** Direct message content and optional referenced-session context. */
-interface PreparedReferencedMessage {
-  /** Readable message content after host mention tokens are removed. */
-  content: ContentBlock[]
-  /** Aggregated untrusted snapshot, absent when the message has no references. */
-  additionalContext?: UserMessage
-}
-```
-
-## 错误
-
-`SessionReferenceError.code` 区分无效配置或输入、自引用、数量限制、源读取失败、预算失败和取消。宿主协议会把这些 code 映射到各自的错误封装，无需检查提示词字节。
-
-```ts type-equiv
-/** Stable failure codes exposed to host adapters. */
-type SessionReferenceErrorCode =
-  | 'SESSION_REFERENCE_INVALID_CONFIG'
-  | 'SESSION_REFERENCE_INVALID_REFERENCE'
-  | 'SESSION_REFERENCE_SELF_REFERENCE'
-  | 'SESSION_REFERENCE_TOO_MANY'
-  | 'SESSION_REFERENCE_READ_FAILED'
-  | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
-  | 'SESSION_REFERENCE_CANCELLED'
-```
-
-<!-- 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="ctxfilereferences--filereferenceservice-abstract-seam"></a>
-
-### `ctx.fileReferences` — `FileReferenceService` (abstract seam)
-
-Host capability for cancellable file-reference discovery.
-
-```ts cordis-catalog
-/**
- * List file and directory candidates for one agent's working directory.
- * @param agent - target agent whose session cwd bounds discovery.
- * @param query - path text following `@` or `@"`.
- * @param signal - caller cancellation.
- * @returns deterministic path-only candidates.
- */
-abstract list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/context/file-reference/src/index.ts`](../../packages/context/file-reference/src/index.ts)
-
-<a id="ctxsessionfilereferences--sessionfilereferences"></a>
-
-### `ctx.sessionFileReferences` — `SessionFileReferences`
-
-Host Remote adapter over the composed file-reference provider.
-
-```ts cordis-catalog
-/**
- * List file and directory candidates for one Agent's working directory.
- * @param agent - target Agent resolved from the Session identity on the wire.
- * @param query - path text following `@` or `@"`.
- * @param signal - caller cancellation.
- * @returns deterministic path-only candidates from the composed provider.
- */
-@Remote list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/api/session-controller/src/file-references.ts`](../../packages/api/session-controller/src/file-references.ts)
-
-<a id="ctxsessionreferenceresolver--sessionreferenceresolver"></a>
-
-### `ctx.sessionReferenceResolver` — `SessionReferenceResolver`
-
-Exact-read consumer that prepares immutable cross-session message context.
-
-```ts cordis-catalog
-/**
- * List reference candidates, ranked by working-directory affinity.
- *
- * Discovery runs at keystroke rate, so titles and subagent labels only ever
- * come from projection reads; sessions without either fall back to their id.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title/display-title substring.
- * @param limit - optional positive result cap.
- * @param signal - optional cancellation boundary for host autocomplete teardown.
- * @returns candidates with canonical mention labels and presentation titles.
- */
-async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
-
-/**
- * Remote face of {@link listCandidates}: the configured candidate limit
- * applies, and every candidate carries the canonical mention a host inserts
- * into the prompt draft.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title substring.
- * @param signal - caller cancellation.
- * @returns mention-carrying candidates in rank order.
- */
-@Remote('candidates') async remoteExportCandidates( agent: Agent, query: string, signal: AbortSignal, ): Promise<SessionReferenceMentionCandidate[]>
-
-/**
- * Snapshot all references for one accepted direct message and return one aggregated durable context.
- * Automatic budgets use the last assembled route, or agent options before any assembly.
- * Missing model capacity or adapter uses 64 KiB; other metadata lookup failures and cancellation reject preparation.
- * Truncated previews include omission facts and a full-snapshot spill locator, or an explicit unavailable notice.
- * Cancellation prevents context publication, including when storage completes after cancellation.
- * @param agent - target agent; references to it are rejected.
- * @param content - already host-normalized readable message content.
- * @param references - structured source sessions in mention order.
- * @param signal - optional cancellation boundary for the active turn.
- * @returns detached content and optional referenced-session context.
- */
-async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
-```
-
-Types: [Agent](core.zh.md) · [ContentBlock](llm-streaming.zh.md)
-
-Source: [`packages/context/session-reference/src/index.ts`](../../packages/context/session-reference/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/kb/extra/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 -->