@deepseek-ai/dsh-session-telemetry-otel 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
+README.md: 585995ce409255df9608bc33b76625374bc67669
+README.zh.md: 7f0b93363fbb4aebb80f0d3cc8108e58ce3f647f

package/README.md

@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-session-telemetry-otel
+
+English | [中文](README.zh.md)
+
+The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam follows session events live, replays the canonical log only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity contains `service.name`/`service.version` from `dsh-llm`'s `APP_IDENTITY` plus this package's anonymous `user.id` (`$DSH_HOME/.userid`, a random UUID created on first use and reset by deleting the file), carried once per export batch rather than per record.
+
+## Config
+
+```yaml
+- id: telemetry-otel
+  name: '@deepseek-ai/dsh-session-telemetry-otel'
+  config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
+    shutdownTimeoutMillis: 3000 # optional; defaults to 3000
+    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
+      url: https://collector.example.com/v1/logs
+      headers:
+        authorization: !!js `Bearer ${process.env.OTLP_TOKEN}`
+    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
+```
+
+| `mode` | Behavior |
+|---|---|
+| `FULL` | Default. Each projected record, including lifecycle ops records, is handed to the OTel SDK immediately. |
+| `FEEDBACK_ONLY` | Each `feedback/record` replays, projects, and redacts the canonical session-log suffix through that event. Later records wait for another feedback event and remain local if none arrives. |
+| `DISABLED` | No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session telemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
+
+Programmatic TypeScript configuration uses the exported `TelemetryMode` enum (`TelemetryMode.FULL`, `TelemetryMode.FEEDBACK_ONLY`, or `TelemetryMode.DISABLED`); raw string literals are not assignable. Serialized Cordis configuration continues to use the string values shown above.
+
+Upload authorization is positive and fail-closed. An unknown direct-construction mode fails before transport configuration is read. Only `FULL` accepts direct `ctx.telemetry.emit()` calls. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability and treats only the exact `feedback/record` object already stored at `session.events[event.seq]` as consent; an independently emitted bus value is ignored. `DISABLED` never constructs the SDK pipeline, even when exporter options are present.
+
+`exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. In uploading modes, `shutdownTimeoutMillis` is a positive finite DSH-owned outer deadline that defaults to 3000 ms, and a non-positive-integer `processor.maxExportBatchSize` also fails at plugin load because the SDK accepts it but then hangs on shutdown. Both SDK blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are SDK behavior tuned through `processor`. The backend implements no `flush()`: the batch processor owns ordinary flushing. During shutdown, OTel awaits `exporter.forceFlush()` before the processor's `exportTimeoutMillis`-bounded completion promise; if that transport promise never settles, this package abandons the wait at `shutdownTimeoutMillis`, logs the contained shutdown failure through the coordinator, and lets application teardown continue. The deadline cannot cancel the SDK transport, so records still pending then may be lost at process exit.
+
+## What leaves the machine
+
+In uploading modes, records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). `FULL` runs redaction at append time; `FEEDBACK_ONLY` retains no telemetry copy and runs the currently mounted rules when feedback triggers canonical-log replay. Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.
+
+## Field mapping
+
+Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)` and alert on severity. In `FULL`, they may also detect crashes by `shutdown`-record absence: the marker is emitted at the session's own disposal or application teardown, and a marker followed by more events is a telemetry reload. In `FEEDBACK_ONLY`, a released prefix normally has no later `shutdown` marker, so its absence is not a crash signal. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. A resumed local log may contain synthetic closers that were never exported; the wire stream stays faithful to records actually handed to the SDK.
+
+## Model Experience
+
+None, as the backend only forwards the seam's redacted records into the OTel SDK pipeline; it never contributes to a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Upstream experimental tree** — `@opentelemetry/sdk-logs` is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
+- **Live-collector behavior belongs to the SDK exporter** — authentication, TLS, throttling, and other real OTLP deployment behavior follow the upstream SDK rather than a package-owned compatibility layer.
+- **Feedback-time snapshot** — `FEEDBACK_ONLY` retains no telemetry-owned copy before feedback. It reads and redacts the current canonical log when feedback is recorded; a crash before feedback uploads nothing, and policy changes before feedback affect what that replay exports.

package/README.zh.md

@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-session-telemetry-otel
+
+[English](README.md) | 中文
+
+[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。其 `mode` 决定 seam 是实时跟随会话事件、仅在记录反馈时回放权威日志，还是将遥测留在本地。上传模式会原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把每条已交接记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份包含 `service.name`/`service.version`（来自 `dsh-llm` 的 `APP_IDENTITY`），以及本包的匿名 `user.id`（`$DSH_HOME/.userid`；首次使用时创建的随机 UUID，删除该文件可重置）；这些身份随每个导出批次携带一次，而非逐条记录携带。
+
+## 配置
+
+```yaml
+- id: telemetry-otel
+  name: '@deepseek-ai/dsh-session-telemetry-otel'
+  config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
+    shutdownTimeoutMillis: 3000 # optional; defaults to 3000
+    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
+      url: https://collector.example.com/v1/logs
+      headers:
+        authorization: !!js `Bearer ${process.env.OTLP_TOKEN}`
+    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
+```
+
+| `mode` | 行为 |
+|---|---|
+| `FULL` | 默认值。每条已投影记录都立即交给 OTel SDK，包括生命周期运维记录。 |
+| `FEEDBACK_ONLY` | 每个 `feedback/record` 都会回放权威会话日志中截至该事件的后缀，并进行投影与脱敏。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
+| `DISABLED` | 不构造协调器、提供方、处理器或导出器。没有遥测记录会离开进程。`feedback/record` 会记录 `session telemetry is DISABLED; nothing will be shared and this feedback remains local`；该事件留在本地会话日志中。 |
+
+程序化 TypeScript 配置使用导出的 `TelemetryMode` 枚举（`TelemetryMode.FULL`、`TelemetryMode.FEEDBACK_ONLY` 或 `TelemetryMode.DISABLED`）；原始字符串字面量不可赋值。序列化后的 Cordis 配置继续使用上表所示的字符串值。
+
+上传授权采用显式许可，且为 fail-closed。通过直接构造传入未知模式时，会在读取传输配置前失败。只有 `FULL` 接受对 `ctx.telemetry.emit()` 的直接调用。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力，并且仅在 `feedback/record` 对象已经存储于 `session.events[event.seq]` 且对象身份完全相同时，才将其视为同意；独立发出的总线值会被忽略。即使存在导出器选项，`DISABLED` 也绝不会构造 SDK 流水线。
+
+`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再等待受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。
+
+## 哪些数据会离开本机
+
+在上传模式中，记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`、反馈文本，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。`FULL` 在追加时运行脱敏；`FEEDBACK_ONLY` 不保留遥测副本，而是在反馈触发权威日志回放时运行当时挂载的规则。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。`DISABLED` 不会构造 SDK 流水线，也不会将任何捕获内容交给后端。
+
+## 字段映射
+
+seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；`severity` → `severityNumber`/`severityText`（INFO 9 / WARN 13 / ERROR 17）；`body` → 结构化日志 body；`attributes` 原样照搬。接收端基于 `(session.id, event.seq)` 去重，并按严重级别告警。在 `FULL` 中，接收端还可通过缺少 `shutdown` 记录检测崩溃：该标记在会话自身 dispose（资源释放）或应用关闭时发出；标记之后出现更多事件，说明遥测发生了重载。在 `FEEDBACK_ONLY` 中，已释放的前缀通常不包含随后的 `shutdown` 标记，因此缺少该标记不是崩溃信号。跨谱系（lineage）的流并不自足：恢复的会话在其自身 id 的流上从上一个进程停止之处继续；fork 出的会话的流从继承边界开始，其前缀位于父会话的流中，由接收端基于 `session.parent_id` + `session.seed_length` 拼接。恢复后的本地日志可能包含从未导出的合成关闭事件；协议流忠实于实际交给 SDK 的记录。
+
+## 模型体验
+
+无。该后端只把 seam 脱敏后的记录转发进 OTel SDK 流水线；它绝不向模型请求贡献任何内容。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 约定不动。
+- **真实 collector 行为属于 SDK 导出器**：身份验证、TLS、限流及其他真实 OTLP 部署行为遵循上游 SDK，不由本包自有兼容层处理。
+- **反馈时快照**：`FEEDBACK_ONLY` 在反馈前不保留遥测自有副本。记录反馈时，它读取并脱敏当前的权威日志；反馈前发生崩溃时什么都不上传，而反馈前的策略变更会影响该次回放的导出内容。

package/lib/index.js

@@ -0,0 +1,198 @@
+import { createRequire } from "node:module";
+import z from "@deepseek-ai/schemastery";
+import { Telemetry, TelemetryCoordinator } from "@deepseek-ai/dsh-session-telemetry";
+import { APP_IDENTITY } from "@deepseek-ai/dsh-llm";
+import { getOrCreateAnonymousUserId } from "@deepseek-ai/dsh-user-id";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+//#region lib/types/index.js
+/**
+* OpenTelemetry Service provider for the DeepSeek Harness telemetry capability.
+*
+* Composes the OTel JS SDK as-is — a `LoggerProvider` with a
+* `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
+* record handed over by the capture coordinator onto `logger.emit()`. After that call,
+* batching, retry, queueing, and loss policy use the SDK's documented behavior, configured
+* verbatim through the `exporter`/`processor` passthroughs. This package owns
+* capture mode and an outer shutdown deadline: the SDK's export timeout does
+* not bound its preceding `forceFlush()` wait.
+*
+* @module @deepseek-ai/dsh-session-telemetry-otel
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+/** Session-sharing policy selected by {@link Config.mode}. */
+var TelemetryMode;
+(function(TelemetryMode) {
+	TelemetryMode["FULL"] = "FULL";
+	TelemetryMode["FEEDBACK_ONLY"] = "FEEDBACK_ONLY";
+	TelemetryMode["DISABLED"] = "DISABLED";
+})(TelemetryMode || (TelemetryMode = {}));
+/** Default session-sharing policy for schema and direct construction. */
+const DEFAULT_TELEMETRY_MODE = TelemetryMode.FULL;
+const DISABLED_FEEDBACK_WARNING = "session telemetry is DISABLED; nothing will be shared and this feedback remains local";
+const NON_CANONICAL_FEEDBACK_WARNING = "session telemetry ignored a feedback event absent from the canonical session log";
+const DROP_RECORD = () => {};
+/** Resolve the default and reject unknown runtime values before transport setup. */
+function resolveMode(mode) {
+	const resolved = mode ?? DEFAULT_TELEMETRY_MODE;
+	switch (resolved) {
+		case TelemetryMode.FULL:
+		case TelemetryMode.FEEDBACK_ONLY:
+		case TelemetryMode.DISABLED: return resolved;
+		default: return assertNever(resolved);
+	}
+}
+/** Fail closed when direct construction bypasses the runtime config schema. */
+function assertNever(value) {
+	throw new Error(`session-telemetry-otel: unsupported mode ${JSON.stringify(value)}`);
+}
+/**
+* Schemastery validator for {@link Config}; cordis runs it before the plugin
+* starts. It checks only the top-level fields; value checks live in the constructor
+* so their errors name the fields. Both SDK option objects pass through unchanged:
+* the SDK defines and validates their fields. Re-declaring them here would
+* silently drop every field this plugin did not repeat.
+*/
+const Config = z.object({
+	mode: z.union(Object.values(TelemetryMode)).default(DEFAULT_TELEMETRY_MODE),
+	exporter: z.any(),
+	processor: z.any(),
+	shutdownTimeoutMillis: z.number()
+});
+/** Default outer allowance for the SDK's complete shutdown sequence. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3e3;
+const MAX_TIMER_DELAY_MILLIS = 2147483647;
+/** Severity mapping from the Service Definition's three-level vocabulary to OTel severity numbers. */
+const SEVERITY = {
+	info: {
+		severityNumber: SeverityNumber.INFO,
+		severityText: "INFO"
+	},
+	warn: {
+		severityNumber: SeverityNumber.WARN,
+		severityText: "WARN"
+	},
+	error: {
+		severityNumber: SeverityNumber.ERROR,
+		severityText: "ERROR"
+	}
+};
+/**
+* The backend plugin — the only entry a deployment loads. It always registers
+* the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+* pipeline and compose {@link TelemetryCoordinator}; `DISABLED` constructs no
+* SDK state and listens only to warn when recorded feedback stays local.
+*/
+var TelemetryOtel = class extends Telemetry {
+	static inject = ["sessions"];
+	static Config = Config;
+	directEmit;
+	provider;
+	shutdownTimeoutMillis;
+	constructor(ctx, config) {
+		const mode = resolveMode(config.mode);
+		super(ctx);
+		if (mode === TelemetryMode.DISABLED) {
+			this.directEmit = DROP_RECORD;
+			this.provider = void 0;
+			this.shutdownTimeoutMillis = DEFAULT_SHUTDOWN_TIMEOUT_MILLIS;
+			ctx.on("session/event", (_session, event) => {
+				if (event.type === "feedback/record") ctx.logger.warn(DISABLED_FEEDBACK_WARNING);
+			});
+			return;
+		}
+		const url = config.exporter?.url;
+		if (url === void 0 || url.length === 0) throw new Error("session-telemetry-otel: exporter.url is required (the full OTLP logs endpoint)");
+		let parsed;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new Error(`session-telemetry-otel: exporter.url is not a valid URL: ${JSON.stringify(url)}`);
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`session-telemetry-otel: exporter.url must be http(s), got ${parsed.protocol}`);
+		const batchSize = config.processor?.maxExportBatchSize;
+		if (batchSize !== void 0 && (!Number.isInteger(batchSize) || batchSize < 1)) throw new Error(`session-telemetry-otel: processor.maxExportBatchSize must be a positive integer, got ${String(batchSize)}`);
+		const shutdownTimeoutMillis = config.shutdownTimeoutMillis ?? 3e3;
+		if (!Number.isFinite(shutdownTimeoutMillis) || shutdownTimeoutMillis <= 0 || shutdownTimeoutMillis > MAX_TIMER_DELAY_MILLIS) throw new Error(`session-telemetry-otel: shutdownTimeoutMillis must be a positive finite number no greater than ${MAX_TIMER_DELAY_MILLIS}, got ${String(shutdownTimeoutMillis)}`);
+		this.shutdownTimeoutMillis = shutdownTimeoutMillis;
+		this.provider = new LoggerProvider({
+			resource: resourceFromAttributes({
+				"service.name": APP_IDENTITY.product,
+				"service.version": APP_IDENTITY.version,
+				"user.id": getOrCreateAnonymousUserId()
+			}),
+			processors: [new BatchLogRecordProcessor({
+				...config.processor,
+				exporter: new OTLPLogExporter(config.exporter)
+			})]
+		});
+		const ledger = this.provider.getLogger("@deepseek-ai/dsh-session-telemetry-otel", version);
+		const ops = this.provider.getLogger("@deepseek-ai/dsh-session-telemetry-otel/ops", version);
+		const enqueue = (record) => {
+			(record.channel === "ops" ? ops : ledger).emit({
+				timestamp: record.time,
+				observedTimestamp: record.time,
+				...SEVERITY[record.severity],
+				body: record.body,
+				attributes: record.attributes
+			});
+		};
+		const backend = {
+			emit: enqueue,
+			shutdown: () => this.shutdown()
+		};
+		if (mode === TelemetryMode.FULL) {
+			this.directEmit = enqueue;
+			new TelemetryCoordinator(ctx, backend, "live");
+			return;
+		}
+		this.directEmit = DROP_RECORD;
+		const coordinator = new TelemetryCoordinator(ctx, backend, "on-demand");
+		ctx.on("session/event", (session, event) => {
+			if (event.type !== "feedback/record") return;
+			if (session.events[event.seq] !== event) {
+				ctx.logger.warn(NON_CANONICAL_FEEDBACK_WARNING);
+				return;
+			}
+			coordinator.captureSession(session, event.seq);
+		});
+	}
+	/**
+	* Hand a direct service record to the SDK only in `FULL`. Direct calls are
+	* no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+	* backend capability created only for the canonical feedback listener.
+	* @param record - the logical record offered directly to the service.
+	*/
+	emit(record) {
+		this.directEmit(record);
+	}
+	/**
+	* Ask the SDK to drain and quiesce, but reject after the backend-owned
+	* deadline. OTel's processor export timeout wraps `exportCompleted` only;
+	* shutdown awaits `exporter.forceFlush()` first, which can remain pending
+	* when the transport never obtains a socket. The provider promise remains
+	* observed after the deadline so a later rejection cannot become unhandled.
+	* `DISABLED` has no provider and resolves immediately.
+	* @returns resolves when the SDK pipeline quiesces or is disabled, or rejects at the configured deadline.
+	*/
+	async shutdown() {
+		if (this.provider === void 0) return;
+		const providerShutdown = this.provider.shutdown();
+		let timer;
+		const deadline = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`session-telemetry-otel: provider shutdown exceeded ${this.shutdownTimeoutMillis}ms`));
+			}, this.shutdownTimeoutMillis);
+		});
+		try {
+			await Promise.race([providerShutdown, deadline]);
+		} finally {
+			/* v8 ignore else -- the Promise executor assigns timer synchronously before this race starts. */
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	}
+};
+//#endregion
+export { Config, DEFAULT_SHUTDOWN_TIMEOUT_MILLIS, DEFAULT_TELEMETRY_MODE, TelemetryMode, TelemetryOtel, TelemetryOtel as default };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-telemetry-otel`.
+* @module @deepseek-ai/dsh-session-telemetry-otel/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-telemetry-otel";
+/** Cordis companion plugin name. */
+const name = "session-telemetry-otel-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: mode selection changes capture handoff, SDK setup, and
+* local diagnostics without mutating session or service state an independent
+* companion can compare. Export remains inside the SDK past the backend boundary.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * OpenTelemetry Service provider for the DeepSeek Harness telemetry capability.
+ *
+ * Composes the OTel JS SDK as-is — a `LoggerProvider` with a
+ * `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
+ * record handed over by the capture coordinator onto `logger.emit()`. After that call,
+ * batching, retry, queueing, and loss policy use the SDK's documented behavior, configured
+ * verbatim through the `exporter`/`processor` passthroughs. This package owns
+ * capture mode and an outer shutdown deadline: the SDK's export timeout does
+ * not bound its preceding `forceFlush()` wait.
+ *
+ * @module @deepseek-ai/dsh-session-telemetry-otel
+ */
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+import { Telemetry, type TelemetryRecord } from '@deepseek-ai/dsh-session-telemetry';
+import { type BatchLogRecordProcessorOptions } from '@opentelemetry/sdk-logs';
+import type { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
+/** Session-sharing policy selected by {@link Config.mode}. */
+export declare enum TelemetryMode {
+    FULL = "FULL",
+    FEEDBACK_ONLY = "FEEDBACK_ONLY",
+    DISABLED = "DISABLED"
+}
+/** Default session-sharing policy for schema and direct construction. */
+export declare const DEFAULT_TELEMETRY_MODE = TelemetryMode.FULL;
+/**
+ * Plugin configuration: one sharing policy, two verbatim SDK option objects,
+ * and one DSH-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
+ */
+export interface Config {
+    /** Sharing policy; defaults to immediate `FULL` delivery. */
+    mode?: TelemetryMode;
+    /**
+     * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
+     * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
+     * `compression`, `keepAlive`, …), owned and documented by the SDK. `url`
+     * is the one field this package requires and validates itself.
+     */
+    exporter?: OTLPExporterNodeConfigBase & {
+        /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
+        url?: string;
+    };
+    /**
+     * Passed verbatim to `BatchLogRecordProcessor` (minus the exporter slot,
+     * which this plugin fills); the SDK owns and documents these knobs.
+     */
+    processor?: Omit<BatchLogRecordProcessorOptions, 'exporter'>;
+    /** Maximum time spent awaiting the SDK provider's complete shutdown path. */
+    shutdownTimeoutMillis?: number;
+}
+/**
+ * Schemastery validator for {@link Config}; cordis runs it before the plugin
+ * starts. It checks only the top-level fields; value checks live in the constructor
+ * so their errors name the fields. Both SDK option objects pass through unchanged:
+ * the SDK defines and validates their fields. Re-declaring them here would
+ * silently drop every field this plugin did not repeat.
+ */
+export declare const Config: z<Config>;
+/** Default outer allowance for the SDK's complete shutdown sequence. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3000;
+/**
+ * The backend plugin — the only entry a deployment loads. It always registers
+ * the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+ * pipeline and compose {@link TelemetryCoordinator}; `DISABLED` constructs no
+ * SDK state and listens only to warn when recorded feedback stays local.
+ */
+export declare class TelemetryOtel extends Telemetry {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly directEmit;
+    private readonly provider;
+    private readonly shutdownTimeoutMillis;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Hand a direct service record to the SDK only in `FULL`. Direct calls are
+     * no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+     * backend capability created only for the canonical feedback listener.
+     * @param record - the logical record offered directly to the service.
+     */
+    emit(record: TelemetryRecord): void;
+    /**
+     * Ask the SDK to drain and quiesce, but reject after the backend-owned
+     * deadline. OTel's processor export timeout wraps `exportCompleted` only;
+     * shutdown awaits `exporter.forceFlush()` first, which can remain pending
+     * when the transport never obtains a socket. The provider promise remains
+     * observed after the deadline so a later rejection cannot become unhandled.
+     * `DISABLED` has no provider and resolves immediately.
+     * @returns resolves when the SDK pipeline quiesces or is disabled, or rejects at the configured deadline.
+     */
+    shutdown(): Promise<void>;
+}
+export default TelemetryOtel;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-telemetry-otel`.
+ * @module @deepseek-ai/dsh-session-telemetry-otel/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-telemetry-otel-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-session-telemetry-otel",
+  "description": "OpenTelemetry backend for the DeepSeek Harness telemetry seam: hands captured session records to the OTel JS SDK's log pipeline",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-telemetry-otel"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.220.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
+    "@opentelemetry/otlp-exporter-base": "^0.220.0",
+    "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-logs": "^0.220.0",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-command-feedback": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-user-id": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-telemetry": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-command-feedback": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-telemetry": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-user-id": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}