Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(telemetry): rename record waterfall

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-27 21:30:28 +08:00
parent 4182dbdc86
commit 0af16387ae
21 changed files with 57 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
packages/cordis/tool-cordis/src/api-catalog.ts
View File

@@ -1280,11 +1280,11 @@ export const EVENT_API: readonly EventApiEntry[] = [
summary: 'Emitted when any prompt provider changes.',
},
{
name: 'telemetry/redact',
name: 'telemetry/record',
mode: 'waterfall',
signature: '\'telemetry/redact\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
jsDoc: '/**\n * Redact one outbound record before it reaches the backend — the seam\'s\n * scrubbing extension point. The seam ships NO rules of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Redaction applies to the exported copy only; the canonical\n * session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n * copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
summary: 'Redact one outbound record before it reaches the backend — the seam\'s scrubbing extension point.',
signature: '\'telemetry/record\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Redaction applies to the exported copy only; the canonical\n * session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n * copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
summary: 'Transform one outbound record before it reaches the backend.',
},
{
name: 'tools/change',

6
packages/telemetry/README.i18n.yaml
View File

@@ -1,6 +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
README.md: 3e20e3ce31de36311529eb5d91382b9bb0049ddd
README.zh.md: a7036f4f119b144aa61de1c25836c980256d4db7
# pnpm run verify-translation-pairing --write packages/telemetry/README.md
README.md: 944cb3f9bac6169feddf8b49bc481cfbe7c6fa9d
README.zh.md: 7be8af93654565cd9fb4d8b4376e0960fd7eb72b

2
packages/telemetry/README.md
View File

@@ -2,7 +2,7 @@
English | [中文](README.zh.md)
Outbound session reporting: the telemetry seam plus its OpenTelemetry backend. The design — the boundary axiom (the harness's aspect ends at `emit()`; delivery is the reporting SDK's), the `telemetry/redact` waterfall (deployment-mounted rules; the seam ships none), the fixed chunk projection, the handoff cursor, and the operational-record channel — is pinned in [the revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
Outbound session reporting: the telemetry seam plus its OpenTelemetry backend. The design — the boundary axiom (the harness's aspect ends at `emit()`; delivery is the reporting SDK's), the `telemetry/record` waterfall (deployment-mounted redaction rules; the seam ships none), the fixed chunk projection, the handoff cursor, and the operational-record channel — is pinned in [the revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
| Package | Role |
|---|---|

2
packages/telemetry/README.zh.md
View File

@@ -2,7 +2,7 @@
[English](README.md) | 中文
面向外部的会话上报：遥测（telemetry）seam 及其 OpenTelemetry 后端。整套设计归档于[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)：边界公理（harness 的职责止于 `emit()`，投递由上报 SDK 负责）、`telemetry/redact` waterfall（瀑布式事件；脱敏规则由部署方挂载，seam 自身不带任何规则）、固定分片投影、handoff 游标，以及运维记录通道。
面向外部的会话上报：遥测（telemetry）seam 及其 OpenTelemetry 后端。整套设计归档于[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)：边界公理（harness 的职责止于 `emit()`，投递由上报 SDK 负责）、`telemetry/record` waterfall（瀑布式事件；脱敏规则由部署方挂载，seam 自身不带任何规则）、固定分片投影、handoff 游标，以及运维记录通道。
| 包 | 职责 |
|---|---|

6
packages/telemetry/session-telemetry-otel/README.i18n.yaml
View File

@@ -1,6 +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
README.md: e345449033b066103fb14e546e8d9909d68fe696
README.zh.md: 6cad58ebc1ad9bab6dc722fcf0d702f500891d32
# pnpm run verify-translation-pairing --write packages/telemetry/session-telemetry-otel/README.md
README.md: 9b208e291e77bee50d9d4fd14808268dca75f2db
README.zh.md: f36cfe74146b779c4ddb1101227cb45a06f0968c

2
packages/telemetry/session-telemetry-otel/README.md
View File

@@ -21,7 +21,7 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
## What leaves the machine
Records carry the complete `event.data` as the seam's `telemetry/redact` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/redact` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry.
Records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry.
## Field mapping

2
packages/telemetry/session-telemetry-otel/README.zh.md
View File

@@ -21,7 +21,7 @@
## 哪些数据会离开本机
记录携带完整的 `event.data`，内容以 seam 的 `telemetry/redact` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/redact` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。
记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。
## 字段映射

6
packages/telemetry/session-telemetry/README.i18n.yaml
View File

@@ -1,6 +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
README.md: 76f9b242ca0b4779a9ab10e5ae93bab1ffb5e581
README.zh.md: d930dc92e41e85c597aaeff840e6e6b03712b06d
# pnpm run verify-translation-pairing --write packages/telemetry/session-telemetry/README.md
README.md: a3820ee8e91a5c513c08df76b149cf3a670ee2ca
README.zh.md: d607a4ab4d953242ede53ff0b5e50bdf69e29ea4

4
packages/telemetry/session-telemetry/README.md
View File

@@ -14,7 +14,7 @@ The coordinator registers, all through the composing fiber's effects: `session/c
## The redact waterfall
Every record passes the `telemetry/redact` waterfall between projection and `emit()` — the seam's scrubbing extension point. The seam 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. Redaction applies to the exported copy only; the canonical session log is never rewritten.
Every record passes the `telemetry/record` waterfall between projection and `emit()` — the seam's scrubbing extension point. The seam 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. Redaction applies to the exported copy only; the canonical session log is never rewritten.
## The handoff cursor
@@ -39,4 +39,4 @@ 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/redact` 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 `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.

4
packages/telemetry/session-telemetry/README.zh.md
View File

@@ -14,7 +14,7 @@
## 脱敏 waterfall
每条记录在投影与 `emit()` 之间都要经过 `telemetry/redact` waterfall（瀑布式事件），这是该 seam 的擦除扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` waterfall（瀑布式事件），这是该 seam 的擦除扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
## handoff 游标
@@ -39,4 +39,4 @@
## 已知限制与延期工作
- **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
- **不内置脱敏规则**：未挂载 `telemetry/redact` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
- **不内置脱敏规则**：未挂载 `telemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。

8
packages/telemetry/session-telemetry/src/coordinator.ts
View File

@@ -2,8 +2,8 @@
* Capture coordinator: the seam's upstream half. Subscribes to the session
* firehose plus the one live-bus relay (`agent/error`), applies the fixed
* chunk projection, builds logical records, runs each through the
* `telemetry/redact` waterfall (deployment-mounted rules; pass-through when
* none), and hands the result to the backend — synchronously, with every
* `telemetry/record` waterfall (deployment-mounted redaction rules;
* pass-through when none), and hands the result to the backend — synchronously, with every
* handler 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.
@@ -178,14 +178,14 @@ export class TelemetryCoordinator {
}
/**
* Run the `telemetry/redact` waterfall over one record and hand the result
* Run the `telemetry/record` waterfall over one record and hand the result
* to the backend. The innermost `next` passes the record through unchanged
* — the seam 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).
*/
private handOff(record: TelemetryRecord): void {
this.backend.emit(this.ctx.waterfall('telemetry/redact', record, () => record))
this.backend.emit(this.ctx.waterfall('telemetry/record', record, () => record))
}
/** Forward the turn-end boundary to the backend's optional flush hint. */

7
packages/telemetry/session-telemetry/src/index.ts
View File

@@ -22,8 +22,9 @@ declare module 'cordis' {
interface Events {
/**
* Redact one outbound record before it reaches the backend — the seam's
* scrubbing extension point. The seam ships NO rules of its own: the
* Transform one outbound record before it reaches the backend. This
* waterfall is the seam'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
@@ -37,7 +38,7 @@ declare module 'cordis' {
* copy; listeners return a (possibly new) record and must not mutate it.
* @mode waterfall
*/
'telemetry/redact'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
}
}

18
packages/telemetry/session-telemetry/tests/redact.spec.ts
View File

@@ -1,5 +1,5 @@
/**
* The `telemetry/redact` waterfall contract: pass-through when no listener is
* The `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.
*/
@@ -35,7 +35,7 @@ async function setup() {
return { ctx, backend, fiber }
}
describe('telemetry/redact waterfall', () => {
describe('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'))
@@ -46,7 +46,7 @@ describe('telemetry/redact waterfall', () => {
it('applies a mounted rule to every outbound record, ops records included', async () => {
const { ctx, backend, fiber } = await setup()
ctx.on('telemetry/redact', (_record, next) => {
ctx.on('telemetry/record', (_record, next) => {
const record = next()
return { ...record, body: { scrubbed: true } }
})
@@ -62,7 +62,7 @@ describe('telemetry/redact waterfall', () => {
it('keeps the canonical log untouched by a mounted rule', async () => {
const { ctx } = await setup()
ctx.on('telemetry/redact', (_record, next) => ({ ...next(), body: null }))
ctx.on('telemetry/record', (_record, next) => ({ ...next(), body: null }))
const session = ctx.sessions.create(SessionId('log'))
session.append('user/message', { content: [{ type: 'text', text: FIXTURE_SECRET }], source: { kind: 'user' } }, { surfaceOp: 'append' })
const logged = session.events[0]!.data as { content: { text: string }[] }
@@ -72,13 +72,13 @@ describe('telemetry/redact waterfall', () => {
it('stacks listeners outermost-first around next()', async () => {
const { ctx, backend } = await setup()
const order: string[] = []
ctx.on('telemetry/redact', (_record, next) => {
ctx.on('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/redact', (_record, next) => {
ctx.on('telemetry/record', (_record, next) => {
order.push('inner')
const record = next()
return { ...record, attributes: { ...record.attributes, inner: 1 } }
@@ -92,8 +92,8 @@ describe('telemetry/redact waterfall', () => {
it('a listener that skips next() replaces everything beneath it', async () => {
const { ctx, backend } = await setup()
const inner = { called: false }
ctx.on('telemetry/redact', () => ({ channel: 'ops', time: 0, severity: 'info', attributes: {}, body: 'replaced' } satisfies TelemetryRecord))
ctx.on('telemetry/redact', (_record, next) => {
ctx.on('telemetry/record', () => ({ channel: 'ops', time: 0, severity: 'info', attributes: {}, body: 'replaced' } satisfies TelemetryRecord))
ctx.on('telemetry/record', (_record, next) => {
inner.called = true
return next()
})
@@ -105,7 +105,7 @@ describe('telemetry/redact waterfall', () => {
it('a throwing rule withholds the record fail-closed without disturbing the log', async () => {
const { ctx, backend } = await setup()
ctx.on('telemetry/redact', () => {
ctx.on('telemetry/record', () => {
throw new Error('rule exploded')
})
const session = ctx.sessions.create(SessionId('closed'))