@deepseek-ai/dsh-session-telemetry 0.0.1-rc.2 → 0.0.1-rc.5

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
-README.md: 707dcfcdb0c8dfbd622630351928ac43562535ec
-README.zh.md: bd080adceebf83cd9e53d72a7093db376cf6cbd1
+README.md: e4ebee1324bc1228d6d97d891159685b05f94e4f
+README.zh.md: 963d5f6d1c5c0f60f5bf14956f3b490d60bd6574

package/README.md

@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The telemetry Service Definition declares the `TelemetryBackend` contract, and its capture coordinator passes session records to any reporting SDK backend that implements it. Capture can follow live session events or replay a canonical session-log prefix on demand. This package stops after it calls `emit()`: batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
+The telemetry Service Definition declares the `SessionTelemetrySink` contract, and its capture coordinator passes session records to any reporting SDK backend that implements it. Capture can follow live session events or replay a canonical session-log prefix on demand. This package stops after it calls `emit()`: batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
 
 ## The backend contract
 
-`TelemetryBackend` has three members: `emit(record)` MUST enqueue without blocking because it runs synchronously during `session/event` or explicit canonical-log replay; optional `flush()` is a fire-and-forget hint after a turn ends, and most backends omit it and use their SDK's normal batching schedule; `shutdown()` drains queued records and resolves when the SDK stops, and disposal awaits it. An implementation that provides `flush()` must order concurrent flushes with the final `shutdown()` drain. `Telemetry` registers this API under the `telemetry` context key; each context accepts one implementation, and a duplicate load throws. A backend constructs `TelemetryCoordinator` with `live` or `on-demand` capture and calls `captureSession(session, throughSeq?)` at its chosen trigger.
+`SessionTelemetrySink` has three members: `emit(record)` MUST enqueue without blocking because it runs synchronously during `session/event` or explicit canonical-log replay; optional `flush()` is a fire-and-forget hint after a turn ends, and most backends omit it and use their SDK's normal batching schedule; `shutdown()` drains queued records and resolves when the SDK stops, and disposal awaits it. An implementation that provides `flush()` must order concurrent flushes with the final `shutdown()` drain. `SessionTelemetryBackend` registers this API under the `sessionTelemetry` context key; each context accepts one implementation, and a duplicate load throws. A backend constructs `SessionTelemetryCoordinator` with `live` or `on-demand` capture and calls `captureSession(session, throughSeq?)` at its chosen trigger.
 
-The service also carries the required [`TelemetrySharingStatus`](#the-sharing-disclosure) `sharing` member: the deployment-selected sharing policy every backend must disclose to human-facing acknowledgement surfaces (the `/feedback` command's confirmation). A consumer renders "not configured" only when no telemetry service is mounted. The seam owns the vocabulary (`full` | `feedback-only` | `disabled`) so any backend can disclose a policy without depending on the OTel package.
+The service also carries the required [`SessionTelemetrySharingStatus`](#the-sharing-disclosure) `sharing` member: the deployment-selected sharing policy every backend must disclose to human-facing acknowledgement surfaces (the `/feedback` command's confirmation). A consumer renders "not configured" only when no telemetry service is mounted. The seam owns the vocabulary (`full` | `feedback-only` | `disabled`) so any backend can disclose a policy without depending on the OTel package.
 
 ## The sharing disclosure
 
@@ -20,7 +20,7 @@ In `live` mode the coordinator registers, all through the composing fiber's effe
 
 ## The redact waterfall
 
-Every record passes the `telemetry/record` waterfall immediately after projection — the Service Definition's scrubbing extension point. This package ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and 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, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
+Every record passes the `sessionTelemetry/record` waterfall immediately after projection — the Service Definition's scrubbing extension point. This package ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and 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, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
 
 ## The handoff cursor
 
@@ -32,7 +32,7 @@ Only the first `assistant/chunk` of each `(turn, step)` ships; the rest are drop
 
 ## The logical record
 
-`TelemetryRecord`: `channel` (`ledger` | `ops`), `time` (epoch ms), `severity` (pre-mapped: ERROR for `tool/result.isError`, `turn/end` error reasons, and `agent-error`; INFO for other captured records, while `telemetry/record` policies may assign WARN), identity-only `attributes` (`session.id`, `event.type`, `event.seq`, plus `session.cwd`/`session.parent_id`/`session.seed_length` when the header has them), and the complete deep-copied `event.data` as `body` — post-redaction. Operational records carry `telemetry.op` (`agent-error` | `shutdown`) and `session.id`, and deliberately NO `event.seq`/`event.type` — signals to alert on, not entries to sum; `agent-error` normalizes its arbitrary thrown value into a stable `{ name, message }` body. Delivery downstream of the handoff is the backend SDK's; duplicates remain possible (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
+`SessionTelemetryRecord`: `channel` (`ledger` | `ops`), `time` (epoch ms), `severity` (pre-mapped: ERROR for `tool/result.isError`, `turn/end` error reasons, and `agent-error`; INFO for other captured records, while `sessionTelemetry/record` policies may assign WARN), identity-only `attributes` (`session.id`, `event.type`, `event.seq`, plus `session.cwd`/`session.parent_id`/`session.seed_length` when the header has them), and the complete deep-copied `event.data` as `body` — post-redaction. Operational records carry `sessionTelemetry.op` (`agent-error` | `shutdown`) and `session.id`, and deliberately NO `event.seq`/`event.type` — signals to alert on, not entries to sum; `agent-error` normalizes its arbitrary thrown value into a stable `{ name, message }` body. Delivery downstream of the handoff is the backend SDK's; duplicates remain possible (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
 
 ## Model Experience
 
@@ -45,5 +45,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **Best-effort delivery** — the cursor marks handed-off, not delivered; a session torn down inside a reload window cannot be re-adopted; whatever sits in a backend queue at crash time is lost. A durable outbox (spool, per-sink cursors, at-least-once) is deferred until a deployment states a crash-loss requirement — see [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
-- **No built-in redaction rules** — with no `telemetry/record` listener mounted, records leave the process exactly as captured, including any credentials embedded in file contents or command output; a deployment exporting to a shared collector owns its rule set.
+- **No built-in redaction rules** — with no `sessionTelemetry/record` listener mounted, records leave the process exactly as captured, including any credentials embedded in file contents or command output; a deployment exporting to a shared collector owns its rule set.
 - **On-demand redaction uses current state** — uncaptured events exist only in the canonical session log. A later `captureSession()` deep-copies and redacts their current values with the policy mounted at that time; there is no capture-time telemetry snapshot or durable pre-capture spool.

package/README.zh.md

@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）Service Definition 声明 `TelemetryBackend` 后端约定，捕获协调器把会话记录传给实现该约定的任意上报 SDK 后端。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。本包调用 `emit()` 后就停止处理：批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不规定也不包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
+遥测（telemetry）Service Definition 声明 `SessionTelemetrySink` 后端约定，捕获协调器把会话记录传给实现该约定的任意上报 SDK 后端。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。本包调用 `emit()` 后就停止处理：批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不规定也不包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端约定
 
-`TelemetryBackend` 有三个成员：`emit(record)` 必须入队且不能阻塞，因为它会在 `session/event` 或显式权威日志回放期间同步执行；可选的 `flush()` 是轮次结束后的提示，调用方不等待结果，多数后端省略它并使用 SDK 的常规批处理计划；`shutdown()` 排空已入队记录，并在 SDK 停止后结束，dispose（资源释放）会等待它。提供 `flush()` 的实现必须安排并发 flush 与 `shutdown()` 最终排空的先后顺序。`Telemetry` 将此 API 注册在 `telemetry` 上下文键下：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 捕获构造 `TelemetryCoordinator`，并在自己选择的触发器中调用 `captureSession(session, throughSeq?)`。
+`SessionTelemetrySink` 有三个成员：`emit(record)` 必须入队且不能阻塞，因为它会在 `session/event` 或显式权威日志回放期间同步执行；可选的 `flush()` 是轮次结束后的提示，调用方不等待结果，多数后端省略它并使用 SDK 的常规批处理计划；`shutdown()` 排空已入队记录，并在 SDK 停止后结束，dispose（资源释放）会等待它。提供 `flush()` 的实现必须安排并发 flush 与 `shutdown()` 最终排空的先后顺序。`SessionTelemetryBackend` 将此 API 注册在 `sessionTelemetry` 上下文键下：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 捕获构造 `SessionTelemetryCoordinator`，并在自己选择的触发器中调用 `captureSession(session, throughSeq?)`。
 
-该服务还携带必需的 [`TelemetrySharingStatus`](#the-sharing-disclosure) `sharing` 成员：每个后端都必须向面向用户的确认 surface（`/feedback` 命令的确认文本）披露的部署级共享策略。消费方只有在未挂载任何遥测服务时才渲染「未配置」。seam 拥有该词汇（`full` | `feedback-only` | `disabled`），因此任何后端都可以披露策略，而无需依赖 OTel 包。
+该服务还携带必需的 [`SessionTelemetrySharingStatus`](#the-sharing-disclosure) `sharing` 成员：每个后端都必须向面向用户的确认 surface（`/feedback` 命令的确认文本）披露的部署级共享策略。消费方只有在未挂载任何遥测服务时才渲染「未配置」。seam 拥有该词汇（`full` | `feedback-only` | `disabled`），因此任何后端都可以披露策略，而无需依赖 OTel 包。
 
 <a id="the-sharing-disclosure"></a>
 
@@ -22,7 +22,7 @@
 
 ## 脱敏 waterfall（瀑布式事件）
 
-每条记录在投影后立即经过 `telemetry/record` waterfall，这是 Service Definition 的脱敏扩展点。本包自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `sessionTelemetry/record` waterfall，这是 Service Definition 的脱敏扩展点。本包自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
 
 ## handoff 游标
 
@@ -34,7 +34,7 @@
 
 ## 逻辑记录
 
-`TelemetryRecord` 包含：`channel`（`ledger` | `ops`）、`time`（epoch 毫秒）、`severity`（预先映射好的严重级别：`tool/result.isError`、`turn/end` 的错误原因与 `agent-error` 映射为 ERROR，其他已捕获记录映射为 INFO，而 `telemetry/record` 策略可以指定 WARN）、只含身份信息的 `attributes`（`session.id`、`event.type`、`event.seq`，header 中存在时再加 `session.cwd`/`session.parent_id`/`session.seed_length`），以及作为 `body` 的完整深拷贝 `event.data`，且以脱敏后的内容为准。运维记录携带 `telemetry.op`（`agent-error` | `shutdown`）和 `session.id`，并刻意不带 `event.seq`/`event.type`：它们是用来告警的信号，不是用来累加的条目；`agent-error` 会把任意抛出值规范化为稳定的 `{ name, message }` 记录主体。交接之后的投递由后端 SDK 负责；重复仍然可能出现（无游标的重新收养、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
+`SessionTelemetryRecord` 包含：`channel`（`ledger` | `ops`）、`time`（epoch 毫秒）、`severity`（预先映射好的严重级别：`tool/result.isError`、`turn/end` 的错误原因与 `agent-error` 映射为 ERROR，其他已捕获记录映射为 INFO，而 `sessionTelemetry/record` 策略可以指定 WARN）、只含身份信息的 `attributes`（`session.id`、`event.type`、`event.seq`，header 中存在时再加 `session.cwd`/`session.parent_id`/`session.seed_length`），以及作为 `body` 的完整深拷贝 `event.data`，且以脱敏后的内容为准。运维记录携带 `sessionTelemetry.op`（`agent-error` | `shutdown`）和 `session.id`，并刻意不带 `event.seq`/`event.type`：它们是用来告警的信号，不是用来累加的条目；`agent-error` 会把任意抛出值规范化为稳定的 `{ name, message }` 记录主体。交接之后的投递由后端 SDK 负责；重复仍然可能出现（无游标的重新收养、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
 
 ## 模型体验
 
@@ -47,5 +47,5 @@
 ## 已知限制与暂缓事项
 
 - **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
-- **不内置脱敏规则**：未挂载 `telemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
+- **不内置脱敏规则**：未挂载 `sessionTelemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
 - **按需脱敏使用当前状态**：未捕获的事件只存在于权威会话日志中。后续的 `captureSession()` 会使用当时挂载的策略，深拷贝并脱敏其当前值；不存在捕获时的遥测快照或持久化的捕获前 spool。

package/lib/index.js

@@ -5,7 +5,7 @@ import { Service } from "@deepseek-ai/cordis";
 * the session firehose plus the one live-bus relay (`agent/error`). Both
 * capture paths apply the fixed chunk projection, build logical records, and
 * run each through the
-* `telemetry/record` waterfall (deployment-mounted redaction rules;
+* `session-telemetry/record` waterfall (deployment-mounted redaction rules;
 * pass-through when none), then hands the result to the backend. Live capture
 * follows the session firehose; on-demand capture replays the canonical log
 * only when requested. Every synchronous handler is self-contained so a
@@ -42,7 +42,7 @@ const handoffCursor = /* @__PURE__ */ new WeakMap();
 * instead of throwing — best-effort reporting must not fail application
 * teardown.
 */
-var TelemetryCoordinator = class {
+var SessionTelemetryCoordinator = class {
 	ctx;
 	backend;
 	/**
@@ -163,7 +163,7 @@ var TelemetryCoordinator = class {
 		});
 	}
 	/**
-	* Run the `telemetry/record` waterfall at capture time. The innermost `next`
+	* Run the `session-telemetry/record` waterfall at capture time. The innermost `next`
 	* passes the record through unchanged — this package ships no rules; exported
 	* data is as clean as the listeners a deployment mounts. Callers run inside
 	* {@link contain}, so a throwing rule withholds the record instead of
@@ -171,7 +171,7 @@ var TelemetryCoordinator = class {
 	* while reading the canonical session log, not when the event was appended.
 	*/
 	redact(record) {
-		return this.ctx.waterfall("telemetry/record", record, () => record);
+		return this.ctx.waterfall("session-telemetry/record", record, () => record);
 	}
 	/** Hand one redacted record to the backend, then advance its ledger cursor. */
 	deliver(session, pending) {
@@ -267,14 +267,14 @@ function identityOf(session, event) {
 //#endregion
 //#region lib/types/index.js
 /**
-* Telemetry Service Definition for the DeepSeek Harness.
+* SessionTelemetryBackend Service Definition for the DeepSeek Harness.
 *
 * This package owns the CAPTURE side of session-event reporting — which records
 * exist (the chunk projection), what they carry (the logical record), when
 * they are captured (adoption, the per-append firehose, lifecycle
 * forwarding), live versus on-demand canonical-log capture, and the HMR
 * cursor. Everything downstream of
-* {@link Telemetry.emit} — batching, retry, queueing, and loss policy — is the
+* {@link SessionTelemetryBackend.emit} — batching, retry, queueing, and loss policy — is the
 * reporting SDK's territory and is deliberately not modelled here. The
 * design and its trade-offs are pinned in
 * .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
@@ -285,12 +285,12 @@ function identityOf(session, event) {
 * 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
-* {@link TelemetryCoordinator} in its constructor to install the capture side.
+* {@link SessionTelemetryCoordinator} in its constructor to install the capture side.
 */
-var Telemetry = class extends Service {
+var SessionTelemetryBackend = class extends Service {
 	constructor(ctx) {
-		super(ctx, "telemetry");
+		super(ctx, "sessionTelemetry");
 	}
 };
 //#endregion
-export { Telemetry, TelemetryCoordinator };
+export { SessionTelemetryBackend, SessionTelemetryCoordinator };

package/lib/types/coordinator.d.ts

@@ -3,7 +3,7 @@
  * the session firehose plus the one live-bus relay (`agent/error`). Both
  * capture paths apply the fixed chunk projection, build logical records, and
  * run each through the
- * `telemetry/record` waterfall (deployment-mounted redaction rules;
+ * `session-telemetry/record` waterfall (deployment-mounted redaction rules;
  * pass-through when none), then hands the result to the backend. Live capture
  * follows the session firehose; on-demand capture replays the canonical log
  * only when requested. Every synchronous handler is self-contained so a
@@ -15,9 +15,9 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
-import type { TelemetryBackend } from './index.ts';
+import type { SessionTelemetrySink } from './index.ts';
 /** Whether capture follows live events or reads the canonical log only when requested. */
-export type TelemetryCapture = 'live' | 'on-demand';
+export type SessionTelemetryCapture = 'live' | 'on-demand';
 /**
  * Install the telemetry capture side onto a context for one backend.
  *
@@ -33,7 +33,7 @@ export type TelemetryCapture = 'live' | 'on-demand';
  * instead of throwing — best-effort reporting must not fail application
  * teardown.
  */
-export declare class TelemetryCoordinator {
+export declare class SessionTelemetryCoordinator {
     private readonly ctx;
     private readonly backend;
     /**
@@ -49,7 +49,7 @@ export declare class TelemetryCoordinator {
      * @param backend - the backend receiving records; owned elsewhere, never disposed here beyond `shutdown()` forwarding.
      * @param capture - follow live events, or wait for explicit canonical-log capture.
      */
-    constructor(ctx: Context, backend: TelemetryBackend, capture?: TelemetryCapture);
+    constructor(ctx: Context, backend: SessionTelemetrySink, capture?: SessionTelemetryCapture);
     /**
      * Project and hand over the canonical session-log suffix after the handoff
      * cursor, optionally stopping at an inclusive sequence boundary. Redaction
@@ -82,7 +82,7 @@ export declare class TelemetryCoordinator {
     /** Project, redact, and hand one event to the backend. */
     private captureEvent;
     /**
-     * Run the `telemetry/record` waterfall at capture time. The innermost `next`
+     * Run the `session-telemetry/record` waterfall at capture time. The innermost `next`
      * passes the record through unchanged — this package ships no rules; exported
      * data is as clean as the listeners a deployment mounts. Callers run inside
      * {@link contain}, so a throwing rule withholds the record instead of

package/lib/types/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * Telemetry Service Definition for the DeepSeek Harness.
+ * SessionTelemetryBackend Service Definition for the DeepSeek Harness.
  *
  * This package owns the CAPTURE side of session-event reporting — which records
  * exist (the chunk projection), what they carry (the logical record), when
  * they are captured (adoption, the per-append firehose, lifecycle
  * forwarding), live versus on-demand canonical-log capture, and the HMR
  * cursor. Everything downstream of
- * {@link Telemetry.emit} — batching, retry, queueing, and loss policy — is the
+ * {@link SessionTelemetryBackend.emit} — batching, retry, queueing, and loss policy — is the
  * reporting SDK's territory and is deliberately not modelled here. The
  * design and its trade-offs are pinned in
  * .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
@@ -16,7 +16,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        telemetry: Telemetry;
+        sessionTelemetry: SessionTelemetryBackend;
     }
     interface Events {
         /**
@@ -37,7 +37,7 @@ declare module '@deepseek-ai/cordis' {
          *   copy; listeners return a (possibly new) record and must not mutate it.
          * @mode waterfall
          */
-        'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord;
+        'session-telemetry/record'(record: SessionTelemetryRecord, next: () => SessionTelemetryRecord): SessionTelemetryRecord;
     }
 }
 /**
@@ -45,10 +45,10 @@ declare module '@deepseek-ai/cordis' {
  * alert with zero configuration: `error` for events whose own outcome flag
  * says so (the tool-result block's `isError`, `turn/end` error reasons) and for
  * `agent-error` operational records. Captured events otherwise default to
- * `info`; `warn` remains available to `telemetry/record` policies and
+ * `info`; `warn` remains available to `session-telemetry/record` policies and
  * backends.
  */
-export type TelemetrySeverity = 'info' | 'warn' | 'error';
+export type SessionTelemetrySeverity = 'info' | 'warn' | 'error';
 /**
  * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
@@ -56,13 +56,13 @@ export type TelemetrySeverity = 'info' | 'warn' | 'error';
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
  * identity so they can never be mistaken for ledger rows.
  */
-export interface TelemetryRecord {
+export interface SessionTelemetryRecord {
     /** 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 TelemetrySeverity}. */
-    severity: TelemetrySeverity;
+    /** Pre-mapped alerting severity; see {@link SessionTelemetrySeverity}. */
+    severity: SessionTelemetrySeverity;
     /**
      * Identity attributes, deliberately minimal: ledger records carry
      * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
@@ -81,11 +81,11 @@ export interface TelemetryRecord {
     body: unknown;
 }
 /**
- * The minimum backend contract the coordinator requires. {@link Telemetry} is
+ * 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.
  */
-export interface TelemetryBackend {
+export interface SessionTelemetrySink {
     /**
      * Hand one record to the backend's pipeline. MUST be a non-blocking
      * enqueue — the coordinator calls this synchronously from the
@@ -95,7 +95,7 @@ export interface TelemetryBackend {
      * never reach the loop.
      * @param record - the logical record to report; owned by the backend after the call.
      */
-    emit(record: TelemetryRecord): void;
+    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
@@ -125,19 +125,19 @@ export interface TelemetryBackend {
 }
 /**
  * Deployment-selected session-sharing policy disclosed by a mounted
- * {@link Telemetry} backend to human-facing acknowledgement surfaces (the
+ * {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
  * `/feedback` command's confirmation text). The seam owns the vocabulary so
  * any backend can disclose a policy without depending on the OTel package;
- * the values mirror the OTel backend's serialized `TelemetryMode` choices.
+ * the values mirror the OTel backend's serialized `SessionTelemetryMode` choices.
  */
-export type TelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled';
+export type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled';
 /**
  * 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
- * {@link TelemetryCoordinator} in its constructor to install the capture side.
+ * {@link SessionTelemetryCoordinator} in its constructor to install the capture side.
  */
-export declare abstract class Telemetry extends Service implements TelemetryBackend {
+export declare abstract class SessionTelemetryBackend extends Service implements SessionTelemetrySink {
     constructor(ctx: Context);
     /**
      * Deployment-selected session-sharing policy, disclosed for acknowledgement
@@ -146,19 +146,19 @@ export declare abstract class Telemetry extends Service implements TelemetryBack
      * when no telemetry service is mounted. The seam owns this vocabulary so the
      * disclosure is backend-independent.
      */
-    abstract readonly sharing: TelemetrySharingStatus;
+    abstract readonly sharing: SessionTelemetrySharingStatus;
     /**
-     * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
+     * 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: TelemetryRecord): void;
-    /** See {@link TelemetryBackend.flush}. */
+    abstract emit(record: SessionTelemetryRecord): void;
+    /** See {@link SessionTelemetrySink.flush}. */
     flush?(): void;
     /**
-     * See {@link TelemetryBackend.shutdown}.
+     * See {@link SessionTelemetrySink.shutdown}.
      * @returns resolves when the backend's pipeline has quiesced.
      */
     abstract shutdown(): Promise<void>;
 }
-export { TelemetryCoordinator, type TelemetryCapture } from './coordinator.ts';
+export { SessionTelemetryCoordinator, type SessionTelemetryCapture } from './coordinator.ts';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-telemetry",
-  "description": "Telemetry seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
-  "version": "0.0.1-rc.2",
+  "description": "SessionTelemetryBackend seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
+  "version": "0.0.1-rc.5",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,15 +32,15 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
   }
 }