@qilin-agent/session-telemetry 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,64 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
+/:
+  en: 5c553664bfb6ebaa
+  zh: 0ad10e1597cb65bc
+/qilin-agent-session-telemetry:
+  en: 90a76261e0971942
+  zh: 95b8990c999aaef6
+/qilin-agent-session-telemetry/summary:
+  en: 2ee6fcb4e68f6c9b
+  zh: 8ddc8d1f3c645757
+/qilin-agent-session-telemetry/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-session-telemetry/use-this-package:
+  en: f103da7913199503
+  zh: 623f7a102c451289
+/qilin-agent-session-telemetry/use-this-package/choosing-and-mounting-a-backend:
+  en: cc1b92c9563ec9e9
+  zh: 6e80c5e002a6c83d
+/qilin-agent-session-telemetry/use-this-package/the-backend-contract:
+  en: e3cc8ee7774a0ad5
+  zh: 3c039339870b8cf9
+/qilin-agent-session-telemetry/use-this-package/what-gets-captured:
+  en: 5b7fbbe1c55997e8
+  zh: d62d9118fd8df2f4
+/qilin-agent-session-telemetry/use-this-package/the-sharing-disclosure:
+  en: 5c325a8aaadf17c7
+  zh: 5c493d2333f82b28
+/qilin-agent-session-telemetry/use-this-package/redacting-records:
+  en: 22ed345bf7746611
+  zh: a57d2eaa878c8cce
+/qilin-agent-session-telemetry/understand-the-implementation:
+  en: cad1e9d195916553
+  zh: 2192f3ce5e2196bd
+/qilin-agent-session-telemetry/understand-the-implementation/design-concept:
+  en: 5527f8d2222119fb
+  zh: 3173640a2f0a0676
+/qilin-agent-session-telemetry/understand-the-implementation/source-map:
+  en: 5dc345ec3dda38b8
+  zh: 189d673734a2c20e
+/qilin-agent-session-telemetry/understand-the-implementation/capture-flow:
+  en: f86c2777668ae89e
+  zh: 710c28c18f3f4402
+/qilin-agent-session-telemetry/understand-the-implementation/the-handoff-cursor:
+  en: c213358e20f27173
+  zh: 84a5501335891f0b
+/qilin-agent-session-telemetry/further-exploration:
+  en: 57e55389f43b5b28
+  zh: 1f7187573723e735
+/qilin-agent-session-telemetry/model-experience:
+  en: 6a6b429828997572
+  zh: bde61df9dab8f840
+/qilin-agent-session-telemetry/model-experience/kv-cache-effect:
+  en: 7593cf5d0d2cedd6
+  zh: f57cc48a1b5cbfa9
+/qilin-agent-session-telemetry/known-limitations-and-deferred-work:
+  en: dc950b1f59a057ec
+  zh: 6f353d426b03abb1
+/qilin-agent-session-telemetry/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+---
+description: "Session-telemetry capture seam for deployments and backend authors choosing a reporting backend, mounting redaction rules, or implementing the backend contract."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/session-telemetry
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Session telemetry lets deployments send ordered copies of session activity for reporting while preserving the canonical session log. Deployments choose one reporting backend and can redact each outbound copy before delivery; without redaction rules, captured data leaves the process unchanged. The handoff is non-blocking, so reporting does not delay session processing. Delivery is best effort, and queued records may be lost if the process crashes.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+As a deployment, choose a backend, mount it, and add redaction rules when records must not leave the process as captured. As a backend author, implement the three-member contract and compose the coordinator with a capture mode.
+
+### Choosing and mounting a backend
+
+Load exactly one backend plugin; it registers `ctx.sessionTelemetry` with the capture coordinator and its delivery pipeline. A duplicate load throws. The required [`sharing` member](#the-sharing-disclosure) reports the deployment mode, not per-session admission or delivery. A consumer may report "not configured" only when no telemetry service is mounted. The `/feedback` command confirms recording without reading this policy.
+
+### The backend contract
+
+A backend implements three members: `emit(record)` must be a non-blocking enqueue because it runs synchronously on the session-event path; optional `flush()` is a fire-and-forget hint after a turn ends, which most backends omit in favor of their SDK's own batching schedule; `shutdown()` drains queued records and resolves when the SDK stops, and disposal awaits it. A backend that implements `flush()` must order concurrent flushes with the final `shutdown()` drain.
+
+### What gets captured
+
+Capture runs in one of two modes. `live` capture follows session events as they are appended, replays already-live sessions at mount time, and records lifecycle markers; `on-demand` capture reads the canonical session log only when the backend requests a prefix through `captureSession(session, throughSeq?)`. Coordinator options select whether stored history is included. Every canonical session event maps to one ledger record in order. An `assistant/message` or `assistant/attempt` record carries its complete embedded compact stream, including failed and retried output. Each ledger record also carries `session.id`, `session.format_version`, the numeric event identity, optional header facts, and a pre-mapped severity (`error` for `tool/result.isError`, `turn/end` error reasons, and `agent-error`; `info` otherwise).
+
+Ledger records carry `sourceEvent` with the owning Session id and a copied event envelope excluding `data`. The redaction waterfall receives `body` as the only payload copy. Backends can reconstruct a complete exported event from the envelope and redacted body without bypassing redaction.
+
+### The sharing disclosure
+
+<a id="the-sharing-disclosure"></a>
+
+Every backend discloses its deployment mode through `sharing`: `full`, `feedback-only`, or `disabled`. A backend may additionally restrict eligible Sessions. This property is not a delivery receipt; handoff is a non-blocking enqueue, and batching, retry, and loss policy belong to the backend SDK.
+
+### Redacting records
+
+<a id="the-redact-waterfall"></a>
+
+Every outbound record passes the `sessionTelemetry/record` waterfall after the coordinator copies its canonical event. This package ships no rules: with no listener mounted, records reach the backend exactly as captured, so exported data is as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; a throwing listener withholds that one record fail-closed. Redaction applies to the outbound copy only — the canonical session log is never rewritten.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the capture design; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The capture package owns complete event capture, redaction, and handoff cursors. Redaction rules must preserve `sourceEvent` for OTel upload; returning a fresh record without it withholds the event with a diagnostic. Its cloned envelope excludes `data`, which is carried only in `body`. The OTel backend owns byte/count scheduling and uses SDK transport/retries. The [revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) owns capture and redaction rationale.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service Definition: `SessionTelemetryBackend`/`SessionTelemetrySink` contract, record vocabulary, `session-telemetry/record` waterfall declaration |
+| [`src/coordinator.ts`](src/coordinator.ts) | Capture: live listeners, lifecycle-local on-demand replay, redaction, handoff cursor, containment |
+
+### Capture flow
+
+Live capture registers Session events, flush hints, shutdown markers, and agent/error observers through the composing fiber’s effects. On-demand capture registers only the disposal effect and reads the requested canonical-log prefix under its history policy. Synchronous handlers contain failures so they cannot affect the agent loop or other listeners.
+
+### The handoff cursor
+
+A module-scope `WeakMap<Session, seq>` records the highest sequence handed off, not delivered. Re-adopting the same object resumes after that cursor. Capture starts at `firstLifecycleSeq`: a new fork includes its child-owned marker and closers, while a restored Session excludes its stored prefix, including prior child turns; explicit `includeHistory: true` starts an unhanded object at seq 0, including restored or fork history. The backend owns capture authorization. Stored history does not itself authorize capture; the OTel backend waits for new explicit feedback. Receivers deduplicate repeated records by `(session.id, session.format_version, event.seq)`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the seam contract is not enough. They move from the shipped backend to the subsystem reference and the decision evidence.
+
+- [OpenTelemetry telemetry backend](../session-telemetry-otel/README.md) — the shipped backend deployments load, with mode and exporter configuration.
+- [Session telemetry subsystem](../../../docs/subsystems/session-telemetry.md) — the capability split and type declarations.
+- [Session telemetry revival decision](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) — rationale, trade-offs, and rejected alternatives.
+- [Session package map](../README.md) — adjacent persistence, projection, title, and telemetry packages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the seam observes the session stream and hands redacted copies outward; it registers nothing model-facing.
+
+#### KV Cache effect
+
+None; the package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define the delivery and data-protection guarantees a deployment gets. They are current package constraints.
+
+- **Best-effort delivery** — the cursor marks handed-off, not delivered; a session torn down inside a reload window cannot be re-adopted, and 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.
+- **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, and there is no capture-time telemetry snapshot or durable pre-capture spool.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,129 @@
+---
+description: "面向部署方与后端作者的会话遥测捕获 seam 说明，用于选择上报后端、挂载脱敏规则或实现后端约定。"
+kind: "package-library"
+---
+
+# @qilin-agent/session-telemetry
+
+[English](README.md) | 中文
+
+## 概述
+
+会话遥测让部署方发送会话活动的有序副本用于上报，同时保留权威会话日志。部署方选择一个上报后端，并可在投递前脱敏每个外发副本；如果没有脱敏规则，捕获的数据将原样离开进程。交接以非阻塞方式完成，因此上报不会延迟会话处理。投递采用尽力而为方式；如果进程崩溃，队列中的记录可能丢失。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+作为部署方，选择一个后端并挂载它，当记录不能以捕获原样离开进程时添加脱敏规则。作为后端作者，实现三成员约定，并以一种捕获模式组装协调器。
+
+### 选择并挂载后端
+
+只加载一个后端插件；它把捕获协调器与投递流水线注册为 `ctx.sessionTelemetry`。重复加载会抛出异常。必需的 [`sharing` 成员](#the-sharing-disclosure) 报告部署模式，不代表会话准入或投递。只有在未挂载任何遥测服务时，消费方才可报告「未配置」。`/feedback` 命令确认记录，不读取此策略。
+
+### 后端约定
+
+后端实现三个成员：`emit(record)` 必须是非阻塞入队，因为它会在会话事件路径上同步执行；可选的 `flush()` 是轮次结束后的即发即忘提示，多数后端为了遵循 SDK 自身的批处理计划而省略它；`shutdown()` 排空已入队记录，并在 SDK 停止后结束，dispose（资源释放）会等待它。实现 `flush()` 的后端必须安排并发 flush 与最终 `shutdown()` 排空的先后顺序。
+
+### 捕获内容
+
+捕获以两种模式之一运行。`live` 捕获在追加时跟随会话事件、在挂载时回放已存活会话并记录生命周期标记；`on-demand` 捕获只在后端通过 `captureSession(session, throughSeq?)` 请求前缀时读取权威会话日志。协调器选项决定是否包含存储历史。每条权威会话事件都按顺序映射为一条 ledger 记录。`assistant/message` 或 `assistant/attempt` 记录会携带完整的嵌入式紧凑流，包括失败和重试输出。每条 ledger 记录还携带 `session.id`、`session.format_version`、数值型事件标识、可选 header 事实与预先映射的严重级别（`tool/result.isError`、`turn/end` 的错误原因与 `agent-error` 映射为 `error`；其余为 `info`）。
+
+ledger 记录携带 `sourceEvent`，其中包含所属 Session id 和不含 `data` 的事件信封副本。脱敏 waterfall 接收的 `body` 是唯一的载荷副本。后端可从信封和脱敏后的 body 重建完整导出事件，而不绕过脱敏。
+
+### 共享披露
+
+<a id="the-sharing-disclosure"></a>
+
+每个后端通过 `sharing` 披露部署模式：`full`、`feedback-only` 或 `disabled`。后端还可限制符合条件的会话。该属性不是投递回执；交接是非阻塞入队，批处理、重试与丢失策略属于后端 SDK。
+
+### 脱敏记录
+
+<a id="the-redact-waterfall"></a>
+
+协调器复制权威事件后，每条外发记录都会立即经过 `sessionTelemetry/record` waterfall（瀑布式事件）。本包不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端，因此导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；抛出异常的监听器以 fail-closed 方式拦下这一条记录。脱敏只作用于外发副本——权威会话日志永不改写。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释捕获设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+捕获包负责完整事件捕获、脱敏和交接游标。脱敏规则必须保留 `sourceEvent` 才能通过 OTel 上传；返回不含它的新记录会阻止该事件上传并产生诊断。复制的 envelope 不含 `data`，数据仅由 `body` 携带。OTel 后端负责字节/条数调度并使用 SDK 传输和重试。[恢复遥测决策记录](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md) 说明捕获和脱敏依据。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service Definition：`SessionTelemetryBackend`/`SessionTelemetrySink` 约定、记录词汇、`session-telemetry/record` waterfall 声明 |
+| [`src/coordinator.ts`](src/coordinator.ts) | 捕获：live 监听器、生命周期本地 on-demand 回放、脱敏、handoff 游标、异常隔离 |
+
+### 捕获流程
+
+实时捕获通过组合 fiber 的 effect 注册 Session 事件、刷新提示、关闭标记与 agent/error 观察器。按需捕获只注册释放 effect，并按历史策略读取请求的权威日志前缀。同步处理器隔离失败，避免影响 agent loop（智能体循环）或其他监听器。
+
+### handoff 游标
+
+模块级 `WeakMap<Session, seq>` 记录已经移交的最高序号，而不是已送达的最高序号。再次接管同一对象时从该游标之后继续。采集从 `firstLifecycleSeq` 开始：新 fork 包含子会话自有的标记与 fork 结束事件；恢复的 Session 排除已存储前缀，包括先前的子会话轮次。显式 `includeHistory: true` 会让尚未移交的对象从 seq 0 开始，包括恢复或 fork 历史。Backend 负责采集授权；已有存储历史本身不构成授权，OTel backend 等待新的显式反馈。接收方通过 `(session.id, session.format_version, event.seq)` 对重复记录去重。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当 seam 约定不够用时阅读以下页面。它们从随附后端逐步进入子系统参考与决策证据。
+
+- [OpenTelemetry 遥测后端](../session-telemetry-otel/README.zh.md)——部署方加载的随附后端，含模式与导出器配置。
+- [会话遥测子系统](../../../docs/subsystems/session-telemetry.zh.md)——能力拆分与类型声明。
+- [会话遥测复活决策](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md)——理由、权衡与被否决的替代方案。
+- [会话包映射](../README.zh.md)——相邻的持久化、投影、标题与遥测包。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为该 seam 观察会话流并把脱敏后的副本交给外部；它不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制定义部署方能得到的投递与数据保护保证。它们是当前包约束。
+
+- **尽力而为的投递**——游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养，崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现。
+- **不内置脱敏规则**——未挂载 `sessionTelemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
+- **按需脱敏使用当前状态**——未捕获的事件只存在于权威会话日志中；后续的 `captureSession()` 会使用当时挂载的策略，深拷贝并脱敏其当前值，且不存在捕获时的遥测快照或持久化的捕获前 spool。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,279 @@
+import { Service } from "@qilin-agent/kylin";
+import { SessionLogOffset, SessionSeq } from "@qilin-agent/session";
+//#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 build one logical record per canonical Session event 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 @qilin-agent/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 its own `session/created` / `session/event` /
+* `session/disposed` 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;
+	options;
+	/**
+	* 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();
+	/**
+	* @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 options - capture mode and history policy.
+	*/
+	constructor(ctx, backend, options = {}) {
+		this.ctx = ctx;
+		this.backend = backend;
+		this.options = options;
+		if ((options.capture ?? "live") === "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");
+	}
+	/**
+	* Copy, redact, 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 start = session.firstLifecycleSeq;
+		const cursor = handoffCursor.get(session) ?? (this.options.includeHistory === true || start === 0 ? -1 : SessionSeq(start - 1));
+		for (const event of session.snapshotEvents(SessionLogOffset(cursor + 1))) {
+			if (throughSeq !== void 0 && event.seq > throughSeq) break;
+			this.contain(() => {
+				this.captureEvent(session, event);
+			});
+		}
+	}
+	/**
+	* Adopt a session and replay after its handoff cursor, then follow live events.
+	* New fork objects include child-owned seed markers and closers. Restored
+	* objects start after the stored prefix, including restored forks. includeHistory starts either object at seq 0;
+	* re-adopting the same object resumes after its cursor.
+	* @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);
+	}
+	/** Copy, redact, and hand one canonical event to the backend. */
+	captureEvent(session, event) {
+		const { data, ...envelope } = event;
+		this.deliver(session, {
+			record: this.redact({
+				sourceEvent: {
+					sessionId: session.id,
+					envelope: structuredClone(envelope)
+				},
+				channel: "ledger",
+				time: event.time,
+				severity: severityOf(event),
+				attributes: identityOf(session, event),
+				body: structuredClone(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
+		}) });
+	}
+	/**
+	* 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.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),
+		"session.format_version": session.header.version,
+		"event.type": event.type,
+		"event.seq": event.seq
+	};
+	const { cwd, parentSession, isSeeded } = session.header;
+	if (cwd !== void 0) attributes["session.cwd"] = cwd;
+	if (parentSession !== void 0) attributes["session.parent_id"] = String(parentSession);
+	if (isSeeded) attributes["session.seed_length"] = session.inheritedEventCount;
+	return attributes;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* SessionTelemetryBackend Service Definition for the QiLin.
+*
+* This package owns the CAPTURE side of session-event reporting — the complete
+* one-record-per-event ledger mirror, what records carry, 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 @qilin-agent/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/types/coordinator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Capture coordinator for the telemetry capability. Live capture subscribes to
+ * the session firehose plus the one live-bus relay (`agent/error`). Both
+ * capture paths build one logical record per canonical Session event 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 @qilin-agent/session-telemetry/coordinator
+ */
+import type { Context } from '@qilin-agent/kylin';
+import { type Session, type SessionSeq as SessionSeqType } from '@qilin-agent/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';
+/** Backend-selected capture mode and history policy. */
+export interface SessionTelemetryCaptureOptions {
+    /** Follow live events, or wait for explicit capture; defaults to live. */
+    capture?: SessionTelemetryCapture;
+    /** Include inherited fork history and stored history from earlier lifecycles; defaults to false. */
+    includeHistory?: boolean;
+}
+/**
+ * Install the telemetry capture side onto a context for one backend.
+ *
+ * Live capture registers its own `session/created` / `session/event` /
+ * `session/disposed` 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;
+    private readonly options;
+    /**
+     * 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;
+    /**
+     * @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 options - capture mode and history policy.
+     */
+    constructor(ctx: Context, backend: SessionTelemetrySink, options?: SessionTelemetryCaptureOptions);
+    /**
+     * Copy, redact, 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?: SessionSeqType): void;
+    /**
+     * Adopt a session and replay after its handoff cursor, then follow live events.
+     * New fork objects include child-owned seed markers and closers. Restored
+     * objects start after the stored prefix, including restored forks. includeHistory starts either object at seq 0;
+     * re-adopting the same object resumes after its cursor.
+     * @param session - the live session to adopt; a second adoption is a no-op.
+     */
+    private adopt;
+    /** Copy, redact, and hand one canonical 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;
+    /**
+     * 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,163 @@
+/**
+ * SessionTelemetryBackend Service Definition for the QiLin.
+ *
+ * This package owns the CAPTURE side of session-event reporting — the complete
+ * one-record-per-event ledger mirror, what records carry, 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 @qilin-agent/session-telemetry
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { SessionEvent, SessionId } from '@qilin-agent/session';
+declare module '@qilin-agent/kylin' {
+    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 {
+    /** Canonical envelope without data; body carries the separately redacted payload. Absent for operational records. */
+    sourceEvent?: {
+        sessionId: SessionId;
+        envelope: Omit<SessionEvent, 'data'>;
+    };
+    /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+    channel: 'ledger' | 'ops';
+    /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+    time: number;
+    /** Pre-mapped alerting severity; see {@link SessionTelemetrySeverity}. */
+    severity: SessionTelemetrySeverity;
+    /**
+     * Identity attributes, deliberately minimal: ledger records carry
+     * `session.id`, `session.format_version`, `event.type`, `event.seq`, plus optional
+     * `session.cwd` / `session.parent_id`; a seeded Session also carries
+     * `session.seed_length` from its exact inherited event count;
+     * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+     * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+     * body is intentionally NOT duplicated here.
+     */
+    attributes: Record<string, string | number>;
+    /**
+     * The complete payload: a deep copy of the session event's `data` for
+     * ledger records (JSON-serializable by `Session.append`'s own
+     * validation), or the op payload for ops records. Never mutated after
+     * handoff.
+     */
+    body: unknown;
+}
+/**
+ * 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 mode, not confirmation of SDK delivery.
+ */
+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 sharing mode, independent of SDK delivery.
+     */
+    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, type SessionTelemetryCaptureOptions } from './coordinator.ts';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@qilin-agent/session-telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "SessionTelemetryBackend seam for the QiLin: session-event capture, projection, redaction, and handoff to a reporting backend",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/session-telemetry"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/session": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/agent": "3.1.4"
+  }
 }