@hasna-internal/kai-session-telemetry 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/README.md
+README.md: e4ebee1324bc1228d6d97d891159685b05f94e4f
+README.zh.md: 718f07db3fb8d8f8a21236dcb917a33ed3e0cad8

package/README.md

@@ -0,0 +1,49 @@
+# @hasna-internal/kai-session-telemetry
+
+English | [中文](README.zh.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
+
+`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 [`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
+
+The acknowledgement of a recorded feedback entry reports whether and how the session is shared, read from the mounted backend's `sharing`. A backend sets the property from its deployment configuration: `full` (every event is handed over as it happens), `feedback-only` (nothing is handed over until a `feedback/record` event releases the unreleased prefix through it), or `disabled` (nothing is handed over at all). Consumers map the status onto user-facing copy; the disclosure never claims delivery — handoff is the non-blocking enqueue, and batching, retry, and loss policy stay the backend SDK's.
+
+## Capture points
+
+In `live` mode the coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, then hand off; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (capture the session's `shutdown` operational record at its termination edge, then retire it), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (capture shutdown for each still-live session, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`). In `on-demand` mode it registers only the dispose effect: `captureSession()` reads the canonical log through an optional inclusive sequence boundary, while flush hints and operational events remain local.
+
+## The redact waterfall
+
+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
+
+A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session. Live capture advances it at append time; on-demand capture advances it only while `captureSession()` hands a requested prefix to the backend. An uncaptured prefix remains solely in the canonical log, so a coordinator reload adds no telemetry-owned recovery state. On replay the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
+
+## The fixed chunk projection
+
+Only the first `assistant/chunk` of each `(turn, step)` ships; the rest are dropped at capture and never advance the cursor. That one chunk is the stream-started signal: `step/start` + first-chunk presence + `assistant/message` presence + the `turn/end` reason distinguish "the request never started" from "the stream died midway" without chunk volume, and time-to-first-token stays computable. Chunk elision makes `seq` gaps routine on the wire — a gap is never a loss signal. Every other event type, including ones merged by plugins this package never heard of, passes through whole.
+
+## The logical record
+
+`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
+
+None, as this package only observes the session stream and hands redacted copies to a reporting backend; 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
+
+- **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 `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

@@ -0,0 +1,53 @@
+# @hasna-internal/kai-session-telemetry
+
+[English](README.md) | 中文
+
+遥测（telemetry）Service Definition 声明 `SessionTelemetrySink` 后端约定，捕获协调器把会话记录传给实现该约定的任意上报 SDK 后端。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。本包调用 `emit()` 后就停止处理：批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不规定也不包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.zh.md)。
+
+## 后端约定
+
+`SessionTelemetrySink` 有三个成员：`emit(record)` 必须入队且不能阻塞，因为它会在 `session/event` 或显式权威日志回放期间同步执行；可选的 `flush()` 是轮次结束后的提示，调用方不等待结果，多数后端省略它并使用 SDK 的常规批处理计划；`shutdown()` 排空已入队记录，并在 SDK 停止后结束，dispose（资源释放）会等待它。提供 `flush()` 的实现必须安排并发 flush 与 `shutdown()` 最终排空的先后顺序。`SessionTelemetryBackend` 将此 API 注册在 `sessionTelemetry` 上下文键下：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 捕获构造 `SessionTelemetryCoordinator`，并在自己选择的触发器中调用 `captureSession(session, throughSeq?)`。
+
+该服务还携带必需的 [`SessionTelemetrySharingStatus`](#the-sharing-disclosure) `sharing` 成员：每个后端都必须向面向用户的确认 surface（`/feedback` 命令的确认文本）披露的部署级共享策略。消费方只有在未挂载任何遥测服务时才渲染「未配置」。seam 拥有该词汇（`full` | `feedback-only` | `disabled`），因此任何后端都可以披露策略，而无需依赖 OTel 包。
+
+<a id="the-sharing-disclosure"></a>
+
+## 共享披露
+
+一条已记录的反馈条目的确认文本会报告该会话是否以及如何被共享，读取自已挂载后端的 `sharing`。后端根据其部署配置设置该属性：`full`（每个事件在发生时立即交接）、`feedback-only`（在 `feedback/record` 事件释放其之前的未释放前缀之前，不交接任何内容）或 `disabled`（完全不交接任何内容）。消费方把状态映射为面向用户的文案；披露从不声称投递——交接是非阻塞入队，批处理、重试与丢失策略仍归后端 SDK。
+
+## 捕获点
+
+在 `live` 模式中，协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏，再交接；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘捕获该会话的 `shutdown` 运维记录，然后将其退役）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（捕获每个仍存活会话的 shutdown，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。在 `on-demand` 模式中，协调器只注册 dispose effect：`captureSession()` 读取权威日志，直至可选的序列号边界（含边界）；flush 提示与运维事件留在本地。
+
+<a id="the-redact-waterfall"></a>
+
+## 脱敏 waterfall（瀑布式事件）
+
+每条记录在投影后立即经过 `sessionTelemetry/record` waterfall，这是 Service Definition 的脱敏扩展点。本包自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
+
+## handoff 游标
+
+一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq。实时捕获在追加时推进游标；按需捕获只有在 `captureSession()` 将请求的前缀交给后端时才推进游标。未捕获的前缀只留在权威日志中，因此协调器重载不会增加遥测自有的恢复状态。回放时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
+
+## 固定分片投影
+
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`；其余分片在捕获时丢弃，且绝不推进游标。这一条分片就是「流已开始」的信号：`step/start`、首分片是否存在、`assistant/message` 是否存在，加上 `turn/end` 的原因，无需分片流量即可区分「请求从未开始」与「流中途夭折」，首个 token 延迟（time-to-first-token）也仍然可以计算。分片省略使导出流中的 `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)` 去重。
+
+## 模型体验
+
+无。本包只观察会话流，并把脱敏后的副本交给上报后端；它绝不向模型请求贡献任何内容。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md)。
+- **不内置脱敏规则**：未挂载 `sessionTelemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
+- **按需脱敏使用当前状态**：未捕获的事件只存在于权威会话日志中。后续的 `captureSession()` 会使用当时挂载的策略，深拷贝并脱敏其当前值；不存在捕获时的遥测快照或持久化的捕获前 spool。

package/lib/index.js

@@ -0,0 +1,296 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/coordinator.js
+/**
+* Capture coordinator for the telemetry capability. Live capture subscribes to
+* 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
+* `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
+* failing backend can never starve other subscribers (cordis `emit` is
+* stop-on-throw) or touch the agent loop. Composed by a backend in its
+* constructor.
+*
+* @module @hasna-internal/kai-session-telemetry/coordinator
+*/
+/**
+* The handoff cursor: per session, the highest `seq` handed to a backend.
+* Deliberately MODULE-scope ambient state — a narrow, documented exception
+* to the registrations-are-effects discipline: cordis has no HMR
+* state-handover API, and keying by the `Session` object (which belongs to
+* the session store and outlives any telemetry fiber) is the only in-process
+* lifetime that lets a re-adopting fiber resume instead of re-handing
+* history. Entries die with their sessions; a missing entry safely means
+* "re-hand everything". Advanced only at emit time — the cursor marks
+* handed-off, not delivered.
+*/
+const handoffCursor = /* @__PURE__ */ new WeakMap();
+/**
+* Install the telemetry capture side onto a context for one backend.
+*
+* Live capture registers the persistence-coordinator listener set plus the
+* `agent/error` relay, all through `ctx.effect()`/`ctx.on()` on the composing
+* fiber, and sweeps already-live sessions (a hot reload does not replay
+* `session/created`). A `session/disposed` captures the session's `shutdown`
+* operational record at its own termination edge and retires it from the
+* adopted set. On-demand capture registers none of those continuous listeners;
+* {@link captureSession} reads the canonical log explicitly and never creates
+* operational records. Disposal captures shutdown markers for live-adopted
+* sessions, then awaits the backend's `shutdown()`; a failure there warns
+* instead of throwing — best-effort reporting must not fail application
+* teardown.
+*/
+var SessionTelemetryCoordinator = class {
+	ctx;
+	backend;
+	/**
+	* Sessions adopted by THIS fiber and still live, for double-adoption
+	* protection and the teardown sweep of unmarked sessions;
+	* `session/disposed` marks and retires entries.
+	*/
+	adopted = /* @__PURE__ */ new Set();
+	/** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
+	chunkSeen = /* @__PURE__ */ new WeakMap();
+	/**
+	* @param ctx - the composing backend's context; listeners bind to its fiber.
+	* @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, backend, capture = "live") {
+		this.ctx = ctx;
+		this.backend = backend;
+		if (capture === "live") {
+			ctx.on("session/created", (session) => {
+				this.adopt(session);
+			});
+			ctx.on("session/disposed", (session) => {
+				this.contain(() => {
+					if (!this.adopted.delete(session)) return;
+					this.deliver(session, { record: this.redact(shutdownRecord(session)) });
+				});
+			});
+			ctx.on("session/event", (session, event) => {
+				this.contain(() => {
+					this.captureEvent(session, event);
+				});
+			});
+			ctx.on("session/flush", (session) => {
+				this.contain(() => {
+					this.hintFlush(session);
+				});
+			});
+			ctx.on("agent/error", ({ agent, turn, step, error }) => {
+				this.contain(() => {
+					this.relayAgentError(agent, turn, step, error);
+				});
+			});
+			for (const session of ctx.sessions.list()) this.adopt(session);
+		}
+		ctx.effect(() => async () => {
+			for (const session of this.adopted) this.contain(() => {
+				this.deliver(session, { record: this.redact(shutdownRecord(session)) });
+			});
+			try {
+				await this.backend.shutdown();
+			} catch (error) {
+				this.ctx.logger.warn(`telemetry: backend shutdown failed: ${String(error)}`);
+			}
+		}, "telemetry capture");
+	}
+	/**
+	* Project and hand over the canonical session-log suffix after the handoff
+	* cursor, optionally stopping at an inclusive sequence boundary. Redaction
+	* runs during this call, so an on-demand caller retains no copied records
+	* before requesting capture and uses the policy mounted at that time.
+	* Backend and policy failures remain contained per event and do not starve
+	* later events in the same replay.
+	* @param session - session whose current canonical-log prefix may be handed over.
+	* @param throughSeq - optional last sequence included in this capture.
+	*/
+	captureSession(session, throughSeq) {
+		const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1;
+		for (const event of session.events) {
+			if (throughSeq !== void 0 && event.seq > throughSeq) break;
+			this.contain(() => {
+				if (event.seq <= cursor) this.track(session, event);
+				else this.captureEvent(session, event);
+			});
+		}
+	}
+	/**
+	* Adopt a session: replay its log THROUGH the projection from the handoff
+	* cursor, then rely on the firehose for everything after. When no cursor
+	* survived, replay starts at the session's construction boundary
+	* (`firstLiveSeq`), not seq 0: constructor seeds never publish on the
+	* firehose, and their content already left the process under another
+	* identity — the same id in a previous process (resume) or the parent's
+	* stream (fork, stitched by receivers via `session.seed_length`). Events
+	* at or below the start still feed the projection state (first-chunk
+	* tracking) without being re-handed, so a resumed fiber drops mid-step
+	* chunk continuations exactly like the fiber that saw the step begin. The
+	* cost, accepted with the capture contract's at-most-once stance: a resume no longer
+	* backfills records a previous process failed to deliver.
+	* @param session - the live session to adopt; a second adoption is a no-op.
+	*/
+	adopt(session) {
+		if (this.adopted.has(session)) return;
+		this.adopted.add(session);
+		this.captureSession(session);
+	}
+	/** Feed the chunk projection without handing off — the ≤cursor half of re-adoption. */
+	track(session, event) {
+		if (event.type === "assistant/chunk") this.seen(session).add(`${event.data.turn}:${event.data.step}`);
+	}
+	/** Project, redact, and hand one event to the backend. */
+	captureEvent(session, event) {
+		if (event.type === "assistant/chunk") {
+			const key = `${event.data.turn}:${event.data.step}`;
+			const seen = this.seen(session);
+			if (seen.has(key)) return;
+			seen.add(key);
+		}
+		this.deliver(session, {
+			record: this.redact({
+				channel: "ledger",
+				time: event.time,
+				severity: severityOf(event),
+				attributes: identityOf(session, event),
+				body: structuredClone(event.data)
+			}),
+			seq: event.seq
+		});
+	}
+	/**
+	* 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
+	* reaching the loop (fail-closed). On-demand capture invokes this waterfall
+	* while reading the canonical session log, not when the event was appended.
+	*/
+	redact(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) {
+		this.backend.emit(pending.record);
+		if (pending.seq !== void 0) handoffCursor.set(session, pending.seq);
+	}
+	/** Forward the turn-end boundary to the backend's optional flush hint. */
+	hintFlush(session) {
+		if (this.adopted.has(session)) this.backend.flush?.();
+	}
+	/** Relay one `agent/error` bus emission as an `agent-error` operational record. */
+	relayAgentError(agent, turn, step, error) {
+		const detail = errorDetail(error);
+		this.deliver(agent.session, { record: this.redact({
+			channel: "ops",
+			time: Date.now(),
+			severity: "error",
+			attributes: {
+				"telemetry.op": "agent-error",
+				"session.id": String(agent.session.id),
+				"agent.id": agent.id,
+				"error.name": detail.name,
+				turn,
+				step
+			},
+			body: detail
+		}) });
+	}
+	/** Lazily create the per-session first-chunk tracking set. */
+	seen(session) {
+		let set = this.chunkSeen.get(session);
+		if (!set) this.chunkSeen.set(session, set = /* @__PURE__ */ new Set());
+		return set;
+	}
+	/**
+	* Run one capture-side step with its exception contained: cordis `emit`
+	* is stop-on-throw, so a throwing listener would starve every subscriber
+	* registered after this plugin — nothing from the backend may escape.
+	*/
+	contain(step) {
+		try {
+			step();
+		} catch (error) {
+			this.ctx.logger.warn(`telemetry: capture step failed: ${String(error)}`);
+		}
+	}
+};
+/**
+* Build the per-session clean-exit marker: emitted at the session's own
+* disposal edge, or at coordinator dispose for sessions still alive then.
+*/
+function shutdownRecord(session) {
+	return {
+		channel: "ops",
+		time: Date.now(),
+		severity: "info",
+		attributes: {
+			"telemetry.op": "shutdown",
+			"session.id": String(session.id)
+		},
+		body: { op: "shutdown" }
+	};
+}
+/** Map an event's own outcome flag to the pre-baked alerting severity. */
+function severityOf(event) {
+	switch (event.type) {
+		case "tool/result": return event.data.message.content[0].isError === true ? "error" : "info";
+		case "turn/end": return event.data.reason.kind === "error" ? "error" : "info";
+		default: return "info";
+	}
+}
+/** Normalize the live bus's arbitrary thrown value into the stable operational-record shape. */
+function errorDetail(error) {
+	const normalized = error instanceof Error ? error : new Error(String(error));
+	return {
+		name: normalized.name,
+		message: normalized.message
+	};
+}
+/** Build the minimal identity attributes: envelope plus self-contained header facts. */
+function identityOf(session, event) {
+	const attributes = {
+		"session.id": String(session.id),
+		"event.type": event.type,
+		"event.seq": event.seq
+	};
+	const { cwd, parentSession, seedLength } = session.header;
+	if (cwd !== void 0) attributes["session.cwd"] = cwd;
+	if (parentSession !== void 0) attributes["session.parent_id"] = String(parentSession);
+	if (seedLength !== void 0) attributes["session.seed_length"] = seedLength;
+	return attributes;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* 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 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.
+*
+* @module @hasna-internal/kai-session-telemetry
+*/
+/**
+* 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 SessionTelemetryCoordinator} in its constructor to install the capture side.
+*/
+var SessionTelemetryBackend = class extends Service {
+	constructor(ctx) {
+		super(ctx, "sessionTelemetry");
+	}
+};
+//#endregion
+export { SessionTelemetryBackend, SessionTelemetryCoordinator };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-session-telemetry`.
+* @module @hasna-internal/kai-session-telemetry/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-session-telemetry";
+/** Cordis companion plugin name. */
+const name = "session-telemetry-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the package's whole output is the backend handoff — a
+* synchronous `emit()` call outside every authoritative event stream — and its
+* capture side never appends session events, so no event/data relation exists
+* for an independent companion to observe.
+*/
+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/coordinator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Capture coordinator for the telemetry capability. Live capture subscribes to
+ * 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
+ * `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
+ * failing backend can never starve other subscribers (cordis `emit` is
+ * stop-on-throw) or touch the agent loop. Composed by a backend in its
+ * constructor.
+ *
+ * @module @hasna-internal/kai-session-telemetry/coordinator
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@hasna-internal/kai-session';
+import type { SessionTelemetrySink } from './index.ts';
+/** Whether capture follows live events or reads the canonical log only when requested. */
+export type SessionTelemetryCapture = 'live' | 'on-demand';
+/**
+ * Install the telemetry capture side onto a context for one backend.
+ *
+ * Live capture registers the persistence-coordinator listener set plus the
+ * `agent/error` relay, all through `ctx.effect()`/`ctx.on()` on the composing
+ * fiber, and sweeps already-live sessions (a hot reload does not replay
+ * `session/created`). A `session/disposed` captures the session's `shutdown`
+ * operational record at its own termination edge and retires it from the
+ * adopted set. On-demand capture registers none of those continuous listeners;
+ * {@link captureSession} reads the canonical log explicitly and never creates
+ * operational records. Disposal captures shutdown markers for live-adopted
+ * sessions, then awaits the backend's `shutdown()`; a failure there warns
+ * instead of throwing — best-effort reporting must not fail application
+ * teardown.
+ */
+export declare class SessionTelemetryCoordinator {
+    private readonly ctx;
+    private readonly backend;
+    /**
+     * Sessions adopted by THIS fiber and still live, for double-adoption
+     * protection and the teardown sweep of unmarked sessions;
+     * `session/disposed` marks and retires entries.
+     */
+    private readonly adopted;
+    /** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
+    private readonly chunkSeen;
+    /**
+     * @param ctx - the composing backend's context; listeners bind to its fiber.
+     * @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: SessionTelemetrySink, capture?: SessionTelemetryCapture);
+    /**
+     * Project and hand over the canonical session-log suffix after the handoff
+     * cursor, optionally stopping at an inclusive sequence boundary. Redaction
+     * runs during this call, so an on-demand caller retains no copied records
+     * before requesting capture and uses the policy mounted at that time.
+     * Backend and policy failures remain contained per event and do not starve
+     * later events in the same replay.
+     * @param session - session whose current canonical-log prefix may be handed over.
+     * @param throughSeq - optional last sequence included in this capture.
+     */
+    captureSession(session: Session, throughSeq?: number): void;
+    /**
+     * Adopt a session: replay its log THROUGH the projection from the handoff
+     * cursor, then rely on the firehose for everything after. When no cursor
+     * survived, replay starts at the session's construction boundary
+     * (`firstLiveSeq`), not seq 0: constructor seeds never publish on the
+     * firehose, and their content already left the process under another
+     * identity — the same id in a previous process (resume) or the parent's
+     * stream (fork, stitched by receivers via `session.seed_length`). Events
+     * at or below the start still feed the projection state (first-chunk
+     * tracking) without being re-handed, so a resumed fiber drops mid-step
+     * chunk continuations exactly like the fiber that saw the step begin. The
+     * cost, accepted with the capture contract's at-most-once stance: a resume no longer
+     * backfills records a previous process failed to deliver.
+     * @param session - the live session to adopt; a second adoption is a no-op.
+     */
+    private adopt;
+    /** Feed the chunk projection without handing off — the ≤cursor half of re-adoption. */
+    private track;
+    /** Project, redact, and hand one event to the backend. */
+    private captureEvent;
+    /**
+     * 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
+     * reaching the loop (fail-closed). On-demand capture invokes this waterfall
+     * while reading the canonical session log, not when the event was appended.
+     */
+    private redact;
+    /** Hand one redacted record to the backend, then advance its ledger cursor. */
+    private deliver;
+    /** Forward the turn-end boundary to the backend's optional flush hint. */
+    private hintFlush;
+    /** Relay one `agent/error` bus emission as an `agent-error` operational record. */
+    private relayAgentError;
+    /** Lazily create the per-session first-chunk tracking set. */
+    private seen;
+    /**
+     * Run one capture-side step with its exception contained: cordis `emit`
+     * is stop-on-throw, so a throwing listener would starve every subscriber
+     * registered after this plugin — nothing from the backend may escape.
+     */
+    private contain;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 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.
+ *
+ * @module @hasna-internal/kai-session-telemetry
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessionTelemetry: SessionTelemetryBackend;
+    }
+    interface Events {
+        /**
+         * 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;
+    }
+}
+/**
+ * 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-result block'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.
+ */
+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;
+ * 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.
+ */
+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 SessionTelemetrySeverity}. */
+    severity: SessionTelemetrySeverity;
+    /**
+     * Identity attributes, deliberately minimal: ledger records carry
+     * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+     * `session.parent_id` / `session.seed_length` when the header has them;
+     * 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;
+}
+/**
+ * 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 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>;
+}
+/**
+ * Deployment-selected session-sharing policy disclosed by a mounted
+ * {@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 `SessionTelemetryMode` choices.
+ */
+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 SessionTelemetryCoordinator} in its constructor to install the capture side.
+ */
+export declare abstract class SessionTelemetryBackend extends Service implements SessionTelemetrySink {
+    constructor(ctx: Context);
+    /**
+     * Deployment-selected session-sharing policy, disclosed for acknowledgement
+     * surfaces that report whether recorded feedback leaves the process. Every
+     * backend must disclose its policy; a consumer renders "not configured" only
+     * when no telemetry service is mounted. The seam owns this vocabulary so the
+     * disclosure is backend-independent.
+     */
+    abstract readonly sharing: SessionTelemetrySharingStatus;
+    /**
+     * 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>;
+}
+export { SessionTelemetryCoordinator, type SessionTelemetryCapture } from './coordinator.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-session-telemetry`.
+ * @module @hasna-internal/kai-session-telemetry/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-telemetry-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,46 @@
+{
+  "name": "@hasna-internal/kai-session-telemetry",
+  "description": "SessionTelemetryBackend seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-telemetry"
+  },
+  "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": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2"
+  }
+}