refactor: apply repository naming contract

Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
This commit is contained in:
Tianyi Cui
2026-08-13 00:36:22 +08:00
parent 101df7cf58
commit a2d0f7f411
3281 changed files with 21730 additions and 21592 deletions

View File

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

View File

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

View File

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

View File

@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-session-telemetry",
"description": "Telemetry seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
"description": "SessionTelemetryBackend seam for the DeepSeek Harness: session-event capture, projection, redaction, and handoff to a reporting backend",
"version": "0.0.1-rc.2",
"publishConfig": {
"access": "restricted"

View File

@@ -3,7 +3,7 @@
* the session firehose plus the one live-bus relay (`agent/error`). Both
* capture paths apply the fixed chunk projection, build logical records, and
* run each through the
* `telemetry/record` waterfall (deployment-mounted redaction rules;
* `session-telemetry/record` waterfall (deployment-mounted redaction rules;
* pass-through when none), then hands the result to the backend. Live capture
* follows the session firehose; on-demand capture replays the canonical log
* only when requested. Every synchronous handler is self-contained so a
@@ -17,14 +17,14 @@
import type { Context } from '@deepseek-ai/cordis'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import type { Agent } from '@deepseek-ai/dsh-agent'
import type { TelemetryBackend, TelemetryRecord, TelemetrySeverity } from './index.ts'
import type { SessionTelemetrySink, SessionTelemetryRecord, SessionTelemetrySeverity } from './index.ts'
/** Whether capture follows live events or reads the canonical log only when requested. */
export type TelemetryCapture = 'live' | 'on-demand'
export type SessionTelemetryCapture = 'live' | 'on-demand'
/** One projected record ready for backend handoff. */
interface ProjectedRecord {
readonly record: TelemetryRecord
readonly record: SessionTelemetryRecord
/** Ledger cursor advanced only after the backend accepts this record. */
readonly seq?: number
}
@@ -57,7 +57,7 @@ const handoffCursor = new WeakMap<Session, number>()
* instead of throwing — best-effort reporting must not fail application
* teardown.
*/
export class TelemetryCoordinator {
export class SessionTelemetryCoordinator {
/**
* Sessions adopted by THIS fiber and still live, for double-adoption
* protection and the teardown sweep of unmarked sessions;
@@ -73,8 +73,8 @@ export class TelemetryCoordinator {
*/
constructor(
private readonly ctx: Context,
private readonly backend: TelemetryBackend,
capture: TelemetryCapture = 'live',
private readonly backend: SessionTelemetrySink,
capture: SessionTelemetryCapture = 'live',
) {
if (capture === 'live') {
ctx.on('session/created', (session) => {
@@ -203,15 +203,15 @@ export class TelemetryCoordinator {
}
/**
* Run the `telemetry/record` waterfall at capture time. The innermost `next`
* Run the `session-telemetry/record` waterfall at capture time. The innermost `next`
* passes the record through unchanged — this package ships no rules; exported
* data is as clean as the listeners a deployment mounts. Callers run inside
* {@link contain}, so a throwing rule withholds the record instead of
* 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(record: TelemetryRecord): TelemetryRecord {
return this.ctx.waterfall('telemetry/record', record, () => record)
private redact(record: SessionTelemetryRecord): SessionTelemetryRecord {
return this.ctx.waterfall('session-telemetry/record', record, () => record)
}
/** Hand one redacted record to the backend, then advance its ledger cursor. */
@@ -271,7 +271,7 @@ export class TelemetryCoordinator {
* 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: Session): TelemetryRecord {
function shutdownRecord(session: Session): SessionTelemetryRecord {
return {
channel: 'ops',
time: Date.now(),
@@ -282,7 +282,7 @@ function shutdownRecord(session: Session): TelemetryRecord {
}
/** Map an event's own outcome flag to the pre-baked alerting severity. */
function severityOf(event: SessionEvent): TelemetrySeverity {
function severityOf(event: SessionEvent): SessionTelemetrySeverity {
switch (event.type) {
case 'tool/result':
return event.data.message.content[0].isError === true ? 'error' : 'info'

View File

@@ -1,12 +1,12 @@
/**
* Telemetry Service Definition for the DeepSeek Harness.
* SessionTelemetryBackend Service Definition for the DeepSeek Harness.
*
* This package owns the CAPTURE side of session-event reporting — which records
* exist (the chunk projection), what they carry (the logical record), when
* they are captured (adoption, the per-append firehose, lifecycle
* forwarding), live versus on-demand canonical-log capture, and the HMR
* cursor. Everything downstream of
* {@link Telemetry.emit} — batching, retry, queueing, and loss policy — is the
* {@link SessionTelemetryBackend.emit} — batching, retry, queueing, and loss policy — is the
* reporting SDK's territory and is deliberately not modelled here. The
* design and its trade-offs are pinned in
* .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
@@ -18,7 +18,7 @@ import { Context, Service } from '@deepseek-ai/cordis'
declare module '@deepseek-ai/cordis' {
interface Context {
telemetry: Telemetry
sessionTelemetry: SessionTelemetryBackend
}
interface Events {
@@ -40,7 +40,7 @@ declare module '@deepseek-ai/cordis' {
* copy; listeners return a (possibly new) record and must not mutate it.
* @mode waterfall
*/
'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
'session-telemetry/record'(record: SessionTelemetryRecord, next: () => SessionTelemetryRecord): SessionTelemetryRecord
}
}
@@ -49,10 +49,10 @@ declare module '@deepseek-ai/cordis' {
* alert with zero configuration: `error` for events whose own outcome flag
* says so (the tool-result block's `isError`, `turn/end` error reasons) and for
* `agent-error` operational records. Captured events otherwise default to
* `info`; `warn` remains available to `telemetry/record` policies and
* `info`; `warn` remains available to `session-telemetry/record` policies and
* backends.
*/
export type TelemetrySeverity = 'info' | 'warn' | 'error'
export type SessionTelemetrySeverity = 'info' | 'warn' | 'error'
/**
* One logical record handed to a backend — the capture contract's whole outbound
@@ -61,13 +61,13 @@ export type TelemetrySeverity = 'info' | 'warn' | 'error'
* home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
* identity so they can never be mistaken for ledger rows.
*/
export interface TelemetryRecord {
export interface SessionTelemetryRecord {
/** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
channel: 'ledger' | 'ops'
/** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
time: number
/** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
severity: TelemetrySeverity
/** Pre-mapped alerting severity; see {@link SessionTelemetrySeverity}. */
severity: SessionTelemetrySeverity
/**
* Identity attributes, deliberately minimal: ledger records carry
* `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
@@ -87,11 +87,11 @@ export interface TelemetryRecord {
}
/**
* The minimum backend contract the coordinator requires. {@link Telemetry} is
* The minimum backend contract the coordinator requires. {@link SessionTelemetryBackend} is
* its service-registered form; tests compose the coordinator with a bare
* implementation of this interface.
*/
export interface TelemetryBackend {
export interface SessionTelemetrySink {
/**
* Hand one record to the backend's pipeline. MUST be a non-blocking
* enqueue — the coordinator calls this synchronously from the
@@ -101,7 +101,7 @@ export interface TelemetryBackend {
* never reach the loop.
* @param record - the logical record to report; owned by the backend after the call.
*/
emit(record: TelemetryRecord): void
emit(record: SessionTelemetryRecord): void
/**
* Optional hint that a turn ended. A backend may forward it to its SDK's
* flush so records are exported after each turn. Called
@@ -132,22 +132,22 @@ export interface TelemetryBackend {
/**
* Deployment-selected session-sharing policy disclosed by a mounted
* {@link Telemetry} backend to human-facing acknowledgement surfaces (the
* {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
* `/feedback` command's confirmation text). The seam owns the vocabulary so
* any backend can disclose a policy without depending on the OTel package;
* the values mirror the OTel backend's serialized `TelemetryMode` choices.
* the values mirror the OTel backend's serialized `SessionTelemetryMode` choices.
*/
export type TelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
export type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
/**
* Loadable form of the backend contract: one implementation per context —
* the cordis `Service` registration under the `telemetry` key throws on a
* duplicate, cordis' standard behavior. A backend composes a
* {@link TelemetryCoordinator} in its constructor to install the capture side.
* {@link SessionTelemetryCoordinator} in its constructor to install the capture side.
*/
export abstract class Telemetry extends Service implements TelemetryBackend {
export abstract class SessionTelemetryBackend extends Service implements SessionTelemetrySink {
constructor(ctx: Context) {
super(ctx, 'telemetry')
super(ctx, 'sessionTelemetry')
}
/**
@@ -157,22 +157,22 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
* when no telemetry service is mounted. The seam owns this vocabulary so the
* disclosure is backend-independent.
*/
abstract readonly sharing: TelemetrySharingStatus
abstract readonly sharing: SessionTelemetrySharingStatus
/**
* See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
* See {@link SessionTelemetrySink.emit} — that declaration is the contract's one home.
* @param record - the logical record to report; owned by the backend after the call.
*/
abstract emit(record: TelemetryRecord): void
abstract emit(record: SessionTelemetryRecord): void
/** See {@link TelemetryBackend.flush}. */
/** See {@link SessionTelemetrySink.flush}. */
flush?(): void
/**
* See {@link TelemetryBackend.shutdown}.
* See {@link SessionTelemetrySink.shutdown}.
* @returns resolves when the backend's pipeline has quiesced.
*/
abstract shutdown(): Promise<void>
}
export { TelemetryCoordinator, type TelemetryCapture } from './coordinator.ts'
export { SessionTelemetryCoordinator, type SessionTelemetryCapture } from './coordinator.ts'

View File

@@ -1,6 +1,6 @@
import { createUserMessage } from '@deepseek-ai/dsh-llm'
/**
* The `telemetry/record` waterfall contract: pass-through when no listener is
* The `session-telemetry/record` waterfall contract: pass-through when no listener is
* mounted, listener stacking and replacement, ops-record coverage, the
* untouched canonical log, and the fail-closed containment of a throwing rule.
*/
@@ -9,16 +9,16 @@ import { describe, expect, it } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import {
TelemetryCoordinator,
type TelemetryBackend,
type TelemetryRecord,
SessionTelemetryCoordinator,
type SessionTelemetrySink,
type SessionTelemetryRecord,
} from '../src/index.ts'
const FIXTURE_SECRET = 'sk-fixture1234567890'
class CollectingBackend implements TelemetryBackend {
records: TelemetryRecord[] = []
emit(record: TelemetryRecord): void {
class CollectingBackend implements SessionTelemetrySink {
records: SessionTelemetryRecord[] = []
emit(record: SessionTelemetryRecord): void {
this.records.push(record)
}
async shutdown(): Promise<void> {}
@@ -31,12 +31,12 @@ async function setup() {
const fiber = await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
return { ctx, backend, fiber }
}
describe('telemetry/record waterfall', () => {
describe('session-telemetry/record waterfall', () => {
it('passes records through unchanged when no listener is mounted', async () => {
const { ctx, backend } = await setup()
const session = ctx.sessions.create(SessionId('w'))
@@ -49,7 +49,7 @@ describe('telemetry/record waterfall', () => {
it('applies a mounted rule to every outbound record, ops records included', async () => {
const { ctx, backend, fiber } = await setup()
ctx.on('telemetry/record', (_record, next) => {
ctx.on('session-telemetry/record', (_record, next) => {
const record = next()
return { ...record, body: { scrubbed: true } }
})
@@ -67,7 +67,7 @@ describe('telemetry/record waterfall', () => {
it('keeps the canonical log untouched by a mounted rule', async () => {
const { ctx } = await setup()
ctx.on('telemetry/record', (_record, next) => ({ ...next(), body: null }))
ctx.on('session-telemetry/record', (_record, next) => ({ ...next(), body: null }))
const session = ctx.sessions.create(SessionId('log'))
session.append('user/message', createUserMessage({
content: [{ type: 'text', text: FIXTURE_SECRET }], source: { kind: 'user' },
@@ -79,13 +79,13 @@ describe('telemetry/record waterfall', () => {
it('stacks listeners outermost-first around next()', async () => {
const { ctx, backend } = await setup()
const order: string[] = []
ctx.on('telemetry/record', (_record, next) => {
ctx.on('session-telemetry/record', (_record, next) => {
order.push('outer-before')
const record = next()
order.push('outer-after')
return { ...record, attributes: { ...record.attributes, outer: 1 } }
})
ctx.on('telemetry/record', (_record, next) => {
ctx.on('session-telemetry/record', (_record, next) => {
order.push('inner')
const record = next()
return { ...record, attributes: { ...record.attributes, inner: 1 } }
@@ -101,8 +101,8 @@ describe('telemetry/record waterfall', () => {
it('a listener that skips next() replaces everything beneath it', async () => {
const { ctx, backend } = await setup()
const inner = { called: false }
ctx.on('telemetry/record', () => ({ channel: 'ops', time: 0, severity: 'info', attributes: {}, body: 'replaced' } satisfies TelemetryRecord))
ctx.on('telemetry/record', (_record, next) => {
ctx.on('session-telemetry/record', () => ({ channel: 'ops', time: 0, severity: 'info', attributes: {}, body: 'replaced' } satisfies SessionTelemetryRecord))
ctx.on('session-telemetry/record', (_record, next) => {
inner.called = true
return next()
})
@@ -116,7 +116,7 @@ describe('telemetry/record waterfall', () => {
it('a throwing rule withholds the record fail-closed without disturbing the log', async () => {
const { ctx, backend } = await setup()
ctx.on('telemetry/record', () => {
ctx.on('session-telemetry/record', () => {
throw new Error('rule exploded')
})
const session = ctx.sessions.create(SessionId('closed'))

View File

@@ -11,10 +11,10 @@ import { Context } from '@deepseek-ai/cordis'
import SessionStore, { SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
import type { Agent } from '@deepseek-ai/dsh-agent'
import {
TelemetryCoordinator,
type TelemetryBackend,
type TelemetryCapture,
type TelemetryRecord,
SessionTelemetryCoordinator,
type SessionTelemetrySink,
type SessionTelemetryCapture,
type SessionTelemetryRecord,
} from '../src/index.ts'
declare module '@deepseek-ai/dsh-session/types' {
@@ -28,15 +28,15 @@ declare module '@deepseek-ai/dsh-session/types' {
}
}
class FakeBackend implements TelemetryBackend {
records: TelemetryRecord[] = []
class FakeBackend implements SessionTelemetrySink {
records: SessionTelemetryRecord[] = []
calls: string[] = []
emitError: Error | undefined
rejectSeq: number | undefined
shutdownError: Error | undefined
shutdownResolved = false
emit(record: TelemetryRecord): void {
emit(record: SessionTelemetryRecord): void {
if (this.emitError) throw this.emitError
if (this.rejectSeq !== undefined && record.attributes['event.seq'] === this.rejectSeq) {
throw new Error(`backend rejected seq ${this.rejectSeq}`)
@@ -54,23 +54,23 @@ class FakeBackend implements TelemetryBackend {
this.shutdownResolved = true
}
ledger(): TelemetryRecord[] {
ledger(): SessionTelemetryRecord[] {
return this.records.filter(r => r.channel === 'ledger')
}
}
async function setup(
backend: FakeBackend = new FakeBackend(),
capture: TelemetryCapture = 'live',
capture: SessionTelemetryCapture = 'live',
) {
const ctx = new Context()
await ctx.plugin(SessionStore)
let coordinator!: TelemetryCoordinator
let coordinator!: SessionTelemetryCoordinator
const fiber = await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => {
coordinator = new TelemetryCoordinator(inner, backend, capture)
coordinator = new SessionTelemetryCoordinator(inner, backend, capture)
},
})
return { ctx, backend, coordinator, fiber }
@@ -87,7 +87,7 @@ function appendTurn(session: Session): void {
}), { surfaceOp: 'append' })
}
describe('TelemetryCoordinator capture', () => {
describe('SessionTelemetryCoordinator capture', () => {
it('hands every appended event over with envelope identity and cloned body', async () => {
const { ctx, backend } = await setup()
const session = liveSession(ctx, 'cap')
@@ -178,7 +178,7 @@ describe('TelemetryCoordinator capture', () => {
})
})
describe('TelemetryCoordinator on-demand capture', () => {
describe('SessionTelemetryCoordinator on-demand capture', () => {
it('captures one canonical-log prefix at a time without following later events', async () => {
const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
const session = liveSession(ctx, 'on-demand-prefix')
@@ -207,7 +207,7 @@ describe('TelemetryCoordinator on-demand capture', () => {
const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
const session = liveSession(ctx, 'on-demand-redacted')
session.append('turn/start', { turn: 1 })
const disposeRule = ctx.on('telemetry/record', (_record, next) => ({
const disposeRule = ctx.on('session-telemetry/record', (_record, next) => ({
...next(),
body: { scrubbed: true },
}))
@@ -244,12 +244,12 @@ describe('TelemetryCoordinator on-demand capture', () => {
expect(first.records).toEqual([])
const second = new FakeBackend()
let coordinator!: TelemetryCoordinator
let coordinator!: SessionTelemetryCoordinator
await ctx.plugin({
name: 'fake-telemetry-after-on-demand-reload',
inject: ['sessions'],
apply: (inner: Context) => {
coordinator = new TelemetryCoordinator(inner, second, 'on-demand')
coordinator = new SessionTelemetryCoordinator(inner, second, 'on-demand')
},
})
coordinator.captureSession(session)
@@ -258,8 +258,8 @@ describe('TelemetryCoordinator on-demand capture', () => {
it('registers no continuous capture, flush, or ops listeners', async () => {
const { ctx, backend, coordinator, fiber } = await setup(new FakeBackend(), 'on-demand')
const redact = vi.fn((_record: TelemetryRecord, next: () => TelemetryRecord) => next())
ctx.on('telemetry/record', redact)
const redact = vi.fn((_record: SessionTelemetryRecord, next: () => SessionTelemetryRecord) => next())
ctx.on('session-telemetry/record', redact)
const session = liveSession(ctx, 'on-demand-ledger-only')
session.append('turn/start', { turn: 1 })
await ctx.parallel('session/flush', session)
@@ -276,7 +276,7 @@ describe('TelemetryCoordinator on-demand capture', () => {
})
})
describe('TelemetryCoordinator adoption', () => {
describe('SessionTelemetryCoordinator adoption', () => {
it('exports an unpublished suffix without re-exporting constructor history', async () => {
const backend = new FakeBackend()
const ctx = new Context()
@@ -286,7 +286,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
const child = ctx.sessions.prepare(SessionId('seeded'), { seed: [...parent.events], meta: {} })
child.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -311,7 +311,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
const ofResumed = () => backend.ledger()
.filter(r => r.attributes['session.id'] === 'resumed')
@@ -341,7 +341,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
child.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
const record = backend.ledger().find(r => r.attributes['session.id'] === 'stitch-child')!
@@ -363,7 +363,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
expect(backend.ledger()).toHaveLength(2)
ctx.sessions.announce(session)
@@ -387,7 +387,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry-2',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, second),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, second),
})
// Only the window events past the cursor are re-handed, and the mid-step
// continuation is re-dropped because ≤cursor events rebuilt the projection.
@@ -410,7 +410,7 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
expect(backend.ledger().map(r => r.attributes['event.seq'])).toEqual([0, 2])
expect(warn).toHaveBeenCalled()
@@ -425,13 +425,13 @@ describe('TelemetryCoordinator adoption', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
expect(backend.ledger().map(r => r.attributes['event.seq'])).toEqual([0, 1])
})
})
describe('TelemetryCoordinator lifecycle and containment', () => {
describe('SessionTelemetryCoordinator lifecycle and containment', () => {
it('forwards session/flush as a hint without awaiting backend work', async () => {
const { ctx, backend } = await setup()
const session = liveSession(ctx)
@@ -466,7 +466,7 @@ describe('TelemetryCoordinator lifecycle and containment', () => {
await ctx.plugin({
name: 'fake-telemetry',
inject: ['sessions'],
apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
apply: (inner: Context) => void new SessionTelemetryCoordinator(inner, backend),
})
expect(() => ctx.sessions.create(SessionId('vetoed'), { meta: {} })).toThrow('vetoed')
expect(backend.records.filter(r => r.channel === 'ops')).toHaveLength(0)

View File

@@ -21,7 +21,7 @@
"path": "../../core/agent"
},
{
"path": "../../support/invariants"
"path": "../../runtime-diagnostics/invariants"
}
]
}