dsh-observe 0.2.26 → 0.2.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/LICENSE +0 -0
  3. package/README.en.md +446 -0
  4. package/README.es.md +446 -0
  5. package/README.hi.md +446 -0
  6. package/README.md +292 -196
  7. package/README.pt.md +446 -0
  8. package/THIRD_PARTY_NOTICES.md +0 -0
  9. package/cordis.patch.yml +6 -1
  10. package/lib/index.js +86 -38
  11. package/lib/typert.host.js +2 -4
  12. package/lib/types/backoff.d.ts +0 -0
  13. package/lib/types/backoff.d.ts.map +0 -0
  14. package/lib/types/backoff.js +0 -0
  15. package/lib/types/backoff.js.map +0 -0
  16. package/lib/types/collector.d.ts +0 -0
  17. package/lib/types/collector.d.ts.map +1 -1
  18. package/lib/types/collector.js +22 -2
  19. package/lib/types/collector.js.map +1 -1
  20. package/lib/types/config.d.ts +9 -0
  21. package/lib/types/config.d.ts.map +1 -1
  22. package/lib/types/config.js +3 -1
  23. package/lib/types/config.js.map +1 -1
  24. package/lib/types/ids.d.ts +0 -0
  25. package/lib/types/ids.d.ts.map +0 -0
  26. package/lib/types/ids.js +0 -0
  27. package/lib/types/ids.js.map +0 -0
  28. package/lib/types/index.d.ts +0 -0
  29. package/lib/types/index.d.ts.map +0 -0
  30. package/lib/types/index.js +0 -0
  31. package/lib/types/index.js.map +0 -0
  32. package/lib/types/model.d.ts +6 -0
  33. package/lib/types/model.d.ts.map +1 -1
  34. package/lib/types/model.js +0 -0
  35. package/lib/types/model.js.map +1 -1
  36. package/lib/types/pipeline.d.ts +0 -0
  37. package/lib/types/pipeline.d.ts.map +0 -0
  38. package/lib/types/pipeline.js +0 -0
  39. package/lib/types/pipeline.js.map +0 -0
  40. package/lib/types/pricing.d.ts +0 -0
  41. package/lib/types/pricing.d.ts.map +0 -0
  42. package/lib/types/pricing.js +0 -0
  43. package/lib/types/pricing.js.map +0 -0
  44. package/lib/types/project.d.ts +22 -0
  45. package/lib/types/project.d.ts.map +1 -1
  46. package/lib/types/project.js +57 -0
  47. package/lib/types/project.js.map +1 -1
  48. package/lib/types/remote.d.ts +0 -0
  49. package/lib/types/remote.d.ts.map +0 -0
  50. package/lib/types/remote.js +0 -0
  51. package/lib/types/remote.js.map +0 -0
  52. package/lib/types/sanitize.d.ts +0 -0
  53. package/lib/types/sanitize.d.ts.map +0 -0
  54. package/lib/types/sanitize.js +0 -0
  55. package/lib/types/sanitize.js.map +0 -0
  56. package/lib/types/sinks.d.ts +0 -0
  57. package/lib/types/sinks.d.ts.map +1 -1
  58. package/lib/types/sinks.js +22 -3
  59. package/lib/types/sinks.js.map +1 -1
  60. package/lib/types/spool.d.ts +0 -0
  61. package/lib/types/spool.d.ts.map +0 -0
  62. package/lib/types/spool.js +0 -0
  63. package/lib/types/spool.js.map +0 -0
  64. package/lib/types/typert.host.d.ts +0 -0
  65. package/lib/types/typert.host.d.ts.map +0 -0
  66. package/lib/types/typert.host.js +0 -0
  67. package/lib/types/typert.host.js.map +0 -0
  68. package/lib/types/version.d.ts +1 -1
  69. package/lib/types/version.d.ts.map +0 -0
  70. package/lib/types/version.js +1 -1
  71. package/lib/types/version.js.map +0 -0
  72. package/lib/types/wire.d.ts +0 -0
  73. package/lib/types/wire.d.ts.map +0 -0
  74. package/lib/types/wire.js +0 -0
  75. package/lib/types/wire.js.map +0 -0
  76. package/package.json +49 -29
  77. package/src/backoff.ts +0 -0
  78. package/src/collector.ts +26 -2
  79. package/src/config.ts +12 -1
  80. package/src/ids.ts +0 -0
  81. package/src/index.ts +0 -0
  82. package/src/model.ts +6 -0
  83. package/src/pipeline.ts +0 -0
  84. package/src/pricing.ts +0 -0
  85. package/src/project.ts +58 -0
  86. package/src/remote.ts +0 -0
  87. package/src/sanitize.ts +0 -0
  88. package/src/sinks.ts +22 -3
  89. package/src/spool.ts +0 -0
  90. package/src/typert.host.ts +0 -0
  91. package/src/version.ts +1 -1
  92. package/src/wire.ts +0 -0
  93. package/README-es.md +0 -354
  94. package/README-hi.md +0 -354
  95. package/README-pt.md +0 -354
  96. package/README-zh.md +0 -354
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.2.27] - 2026-11-05
4
+
5
+ ### Changed
6
+
7
+ - **Host 0.2.2 line support.** devDependencies move from 0.2.1-rc.2 to 0.2.2-rc.1, cordis to 4.1.0 / include 1.1.0 / loader 1.1.0, and schemastery to ~3.19.0 so a single copy resolves against `@deepseek-ai/dsh-llm` 0.2.2. `engines.dsh` appends `>=0.2.2-0 <0.3.0` (append-only) and `engines.node` becomes `^22.19.0 || >=24.9.0`.
8
+
9
+ ### Fixed
10
+
11
+ - Add `@deepseek-ai/dsh-package-manifest`: `@deepseek-ai/dsh-llm` 0.2.2's published types import it but its manifest does not declare it.
12
+
3
13
  ## [0.2.26] - 2026-10-24
4
14
 
5
15
  ### Fixed
package/LICENSE CHANGED
File without changes
package/README.en.md ADDED
@@ -0,0 +1,446 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-observe-hero-en-dark.webp">
5
+ <img src="docs/assets/dsh-observe-hero-en-light.webp" width="100%" alt="dsh-observe banner: plugin name, value lines and install command on the left; on the right a trace waterfall for one turn — turn, step, tool-call and LLM spans on a time axis, token counts on the LLM bars, and a strip of spans, tokens, USD cost and context-pressure metrics; the card notes that sanitization runs before the queue and names OTLP and Langfuse as the destinations">
6
+ </picture>
7
+
8
+ # dsh-observe
9
+
10
+ **Turn every session into standard OTLP traces and Langfuse observations—sanitized before anything leaves, exporting nothing by default.**
11
+
12
+ Observability exporter for DeepSeek Harness: turn/step/tool/LLM spans, token and USD cost metrics, async batching, a bounded offline buffer, and exponential-backoff retries; use OTLP, Langfuse, or both.
13
+
14
+ [Install](#three-step-setup) · [Configuration](#configuration) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
15
+
16
+ [![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
17
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.1%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibility)
18
+ [![npm](https://img.shields.io/npm/v/dsh-observe?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-observe)
19
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-observe/ci.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-observe/actions/workflows/ci.yml)
20
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibility)
21
+
22
+ [![Stars](https://img.shields.io/github/stars/PerryLink/dsh-observe?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-observe/stargazers)
23
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-observe?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-observe)
24
+ [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-observe?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-observe?ref=badge)
25
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-observe/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-observe)
26
+ [![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
27
+ [![Gitee](https://img.shields.io/badge/Gitee-mirror-C71D23?style=flat-square&labelColor=2B3245&logo=gitee)](https://gitee.com/perrylink/dsh-observe)
28
+
29
+ ```sh
30
+ dsh plugin --profile <name> add dsh-observe
31
+ ```
32
+
33
+ </div>
34
+
35
+ <sub>Community plugin, not affiliated with DeepSeek. Only repository: <https://github.com/PerryLink/dsh-observe> (Gitee is a mirror).</sub>
36
+
37
+ ## What it is
38
+
39
+ `dsh-observe` translates the harness `session/event` stream into standard observability protocols: one trace per turn, a span each for steps, tool calls, and LLM generations, cumulative token and cost metrics, and prompt/completion bodies that are sanitized and truncated before they are queued. It only exports: it registers no model tools and no user-facing command, and every behaviour is driven by configuration. Configure OTLP or Langfuse, restart, and the data flows on its own; leave it unconfigured and nothing is captured at all.
40
+
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-observe-flow-v5-dark.svg">
43
+ <img src="docs/assets/dsh-observe-flow-v5-light.svg" width="100%" alt="dsh-observe structure (a fork into two pipelines around a bounded spool): session/event feeds the collector (turn, step, tool and llm spans plus observe.tokens, observe.cost and observe.context_tokens metrics, deterministic sha256 ids), then sanitize (structural key redaction, builtin secret patterns, prompt/completion 4000 and tool 2000/2000 character budgets) cleans every record before any queue; the record forks into two independent pipelines, otlp and langfuse, each a queue (256 records or 5000ms, maxQueueRecords 2000) into flush/retry (5 attempts, 1000ms × 2 backoff capped at 60000ms) into its own endpoint; retry exhaustion and queue overflow spill into the bounded storage-domain spool between the lanes (10000 records, oldest-first eviction, zod re-validation on read, survives restart), drained back into both endpoints every 30000ms along the dashed rail on the right; the optional remote surface observe/status and observe/setEnabled sits bottom-left, and the bottom band states the off-by-default contract and the three listened events">
44
+ </picture>
45
+
46
+ ## Three-step setup
47
+
48
+ 1. **Install** (pick one):
49
+
50
+ ```sh
51
+ # git channel (latest main; the prepare script builds with production dependencies only)
52
+ dsh plugin --profile web add github:PerryLink/dsh-observe
53
+ # npm channel (published version)
54
+ dsh plugin --profile web add dsh-observe
55
+ # tarball channel: pnpm pack in this repo, then
56
+ dsh plugin --profile web add ./dsh-observe-<version>.tgz
57
+ ```
58
+
59
+ > If pnpm reports `ERR_PNPM_IGNORED_BUILDS` for this package (esbuild's harmless platform-binary validation), add `allowBuilds: { esbuild: true }` to your `pnpm-workspace.yaml`; the `dsh` CLI prints the exact snippet.
60
+
61
+ 2. **Minimal configuration** (turn `enabled` on in the profile patch and configure at least one backend; the row ships disabled in `cordis.patch.yml`):
62
+
63
+ ```yaml
64
+ - insert:
65
+ - id: dsh-observe
66
+ name: dsh-observe
67
+ config:
68
+ enabled: true
69
+ otlp:
70
+ endpoint: http://localhost:4318
71
+ ```
72
+
73
+ Langfuse works the same way: `langfuse.baseUrl` + `langfuse.publicKey` + `langfuse.secretKey`. Both backends can be on at once.
74
+
75
+ 3. **Verify it is live**:
76
+
77
+ ```sh
78
+ dsh --profile web --dump-config | grep -A2 'id: dsh-observe'
79
+ ```
80
+
81
+ No user-facing command is registered, so there is no manual `/observe` trigger. With `remote.enabled: true`, a settings page can read the configured backends, queue depths, and buffer occupancy through `observe/status`.
82
+
83
+ **Uninstall**: `dsh plugin --profile web remove dsh-observe` (or delete the row from the profile patch).
84
+
85
+ <details>
86
+ <summary>Install from the DSH Desktop market</summary>
87
+
88
+ Every PerryLink plugin can be browsed in the built-in DSH Desktop market: **Market → Sources → add source → paste** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ select it**. Installation still goes through the market's npm identity check and your confirmation.
89
+
90
+ </details>
91
+
92
+ ## Core capabilities
93
+
94
+ `dsh-observe` turns the session event stream into standard observability protocols:
95
+
96
+ - **Spans** — turn, step, tool-call (duration, status, retry derivation), and LLM generation spans, linked into per-turn traces with deterministic ids.
97
+ - **Metrics** — per-provider/model token counters, USD cost counters (configurable pricing table), and the optional context-pressure gauge from `ctx.tokenMeter`.
98
+ - **Sanitized capture** — prompt and completion bodies pass structural key-name redaction, built-in secret patterns, your patterns, and character budgets before anything is queued or sent.
99
+ - **Reliability** — async batching (size- and timer-triggered), a bounded durable offline buffer (storage-domain, oldest-first eviction), and deterministic exponential-backoff retries; undeliverable batches survive restarts.
100
+ - **Runtime kill switch** — the optional Typert remote (`observe/status`, `observe/setEnabled`) lets a settings page stop and resume exporting without unmounting.
101
+ - **Off by default** — `enabled: true` plus at least one backend is the explicit opt-in; nothing is captured or exported otherwise.
102
+
103
+ ```text
104
+ session/event stream
105
+ │ collector (turn/step/tool/llm spans, metrics)
106
+ │ sanitize (keys, secrets, budgets)
107
+ ├──▶ pipeline "otlp" ── queue ── flush ──▶ OTLP /v1/traces + /v1/metrics
108
+ │ └─ retry/backoff ─┐
109
+ ├──▶ pipeline "langfuse" ── queue ── flush ──▶ Langfuse ingestion
110
+ │ └─ retry/backoff ─┤
111
+ └────────── durable spool (offline buffer, bounded) ◀┘
112
+ ```
113
+
114
+ ### Surfaces
115
+
116
+ This plugin registers **no model tools** and no user-facing command — it is a background exporter. Its whole surface is three things:
117
+
118
+ - **Consumes** `session/event` (span/metric collection), `session/flush` (best-effort export kick — the durability checkpoint never waits on a remote backend), and `session/disposed`.
119
+ - **Optional remote service** `observe` (`remote.enabled`, off by default) — `observe/status` returns the kill-switch state, configured backends, queue depths, and buffer occupancy; `observe/setEnabled` stops and resumes exporting at runtime.
120
+ - **The single injected service key** `storageDomain`, used for the durable offline buffer table.
121
+
122
+ ### Examples
123
+
124
+ There is no manual trigger: after installation, turn `enabled` on with the minimal configuration above and restart; traces and metrics show up in the OTLP backend, observations show up in Langfuse. To confirm it is collecting, look at the first trace the backend receives; to confirm it is shipping, watch `observe/status` queue depths fall back as the session progresses.
125
+
126
+ ## Configuration
127
+
128
+ All tunables are Schemastery `Config` fields (changeable from cordis.yml / the profile patch). An id-targeted override replaces the whole row — restate every key you need. [`cordis.patch.yml`](cordis.patch.yml) documents each key inline.
129
+
130
+ Most-used keys:
131
+
132
+ | Key | Default | Meaning |
133
+ |---|---|---|
134
+ | `enabled` | `false` | Master switch; `true` plus at least one backend is the explicit opt-in |
135
+ | `otlp.endpoint` | *(required)* | OTLP base URL; `/v1/traces` and `/v1/metrics` are appended by the plugin |
136
+ | `otlp.serviceName` | `deepseek-harness` | `service.name` resource attribute |
137
+ | `langfuse.baseUrl` | `https://cloud.langfuse.com` | Langfuse base URL |
138
+ | `langfuse.traceName` | `session {session} turn {turn}` | Trace-name template; `{session}`/`{turn}` interpolate per trace |
139
+ | `capture.llm` | `true` | LLM generation spans |
140
+ | `llm.prompt` | `true` | Capture the sanitized request prompt (`false` = sizes only) |
141
+ | `llm.reasoning` | `true` | Capture reasoning separately as `gen_ai.completion.reasoning` (`false` = answer only) |
142
+ | `batch.maxBufferRecords` | `10000` | Durable offline buffer bound; oldest records drop first |
143
+ | `remote.enabled` | `false` | Mount the `observe` Typert remote (runtime kill switch) |
144
+
145
+ <details>
146
+ <summary>Full configuration table (48 keys)</summary>
147
+
148
+ | Key | Default | Meaning |
149
+ |---|---|---|
150
+ | `enabled` | `false` | Master switch; `true` plus at least one backend is the explicit opt-in |
151
+ | `otlp` | `null` | OTLP backend config, or `null` to disable it |
152
+ | `otlp.endpoint` | *(required)* | OTLP base URL; `/v1/traces` and `/v1/metrics` are appended |
153
+ | `otlp.serviceName` | `deepseek-harness` | `service.name` resource attribute |
154
+ | `otlp.serviceVersion` | *(none)* | `service.version` resource attribute |
155
+ | `otlp.headers` | `{}` | Extra headers merged into every export request |
156
+ | `otlp.timeoutMs` | `10000` | Per-request timeout |
157
+ | `langfuse` | `null` | Langfuse backend config, or `null` to disable it |
158
+ | `langfuse.baseUrl` | `https://cloud.langfuse.com` | Langfuse base URL |
159
+ | `langfuse.publicKey` | *(required)* | Project public key |
160
+ | `langfuse.secretKey` | *(required)* | Project secret key |
161
+ | `langfuse.release` | *(none)* | Release tag stamped onto traces |
162
+ | `langfuse.traceName` | `session {session} turn {turn}` | Trace-name template; `{session}`/`{turn}` interpolate per trace |
163
+ | `langfuse.tags` | `[]` | Static tags stamped onto every trace |
164
+ | `langfuse.timeoutMs` | `10000` | Per-request timeout |
165
+ | `capture.turns` | `true` | Turn lifecycle spans |
166
+ | `capture.steps` | `true` | Step lifecycle spans |
167
+ | `capture.tools` | `true` | Tool-call spans with sanitized arguments/results |
168
+ | `capture.llm` | `true` | LLM generation spans |
169
+ | `llm.prompt` | `true` | Capture the sanitized request prompt (`false` = sizes only) |
170
+ | `llm.completion` | `true` | Capture the sanitized completion (`false` = sizes only) |
171
+ | `llm.reasoning` | `true` | Capture reasoning separately as `gen_ai.completion.reasoning` (`false` = answer only) |
172
+ | `metadata.sessionId` | `true` | Session id attribute |
173
+ | `metadata.cwd` | `false` | Session working directory (a local path — off by default) |
174
+ | `metadata.agentPreset` | `true` | Agent preset id attribute |
175
+ | `metadata.model` | `true` | Provider/model attributes |
176
+ | `metrics.tokens` | `true` | Per-provider/model token counters |
177
+ | `metrics.cost` | `true` | USD cost counters (need `pricing` rules to match) |
178
+ | `metrics.contextTokens` | `true` | Context-pressure gauge (needs `ctx.tokenMeter`) |
179
+ | `pricing` | `[]` | Pricing table, first match wins: `{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? }` |
180
+ | `sanitize.enabled` | `true` | Redaction master switch (`false` disables redaction, never truncation) |
181
+ | `sanitize.redactKeys` | `[]` | Extra key-name substrings (key/token/secret/password/authorization/credential/apiKey are always included) |
182
+ | `sanitize.redactPatterns` | `[]` | Extra secret regular expressions |
183
+ | `sanitize.truncatePromptChars` | `4000` | Prompt character budget |
184
+ | `sanitize.truncateCompletionChars` | `4000` | Completion character budget |
185
+ | `sanitize.truncateToolInputChars` | `2000` | Tool argument character budget |
186
+ | `sanitize.truncateToolOutputChars` | `2000` | Tool result character budget |
187
+ | `sanitize.truncateAttributeChars` | `512` | Span attribute string budget |
188
+ | `batch.maxRecords` | `256` | Flush once the queue holds this many records |
189
+ | `batch.flushIntervalMs` | `5000` | Timer flush interval |
190
+ | `batch.maxQueueRecords` | `2000` | In-memory queue bound; excess spills to the buffer |
191
+ | `batch.maxBufferRecords` | `10000` | Durable offline buffer bound; oldest records drop first |
192
+ | `batch.bufferRetryIntervalMs` | `30000` | Offline buffer retry interval |
193
+ | `retry.maxAttempts` | `5` | Attempts per batch, including the first try |
194
+ | `retry.baseDelayMs` | `1000` | First backoff delay |
195
+ | `retry.factor` | `2` | Backoff multiplier per consecutive failure |
196
+ | `retry.maxDelayMs` | `60000` | Backoff ceiling |
197
+ | `remote.enabled` | `false` | Mount the `observe` Typert remote (runtime kill switch) |
198
+
199
+ </details>
200
+
201
+ > ⚠️ **Reasoning compliance note** — `llm.reasoning` is on by default and reasoning is exported separately as `gen_ai.completion.reasoning` (never inside `gen_ai.completion`; in Langfuse it rides in the generation metadata). Chain-of-thought may contain the user's raw input or context the model quotes verbatim, so **evaluate the compliance impact before exporting it**. Set `llm.reasoning: false` to omit it; `llm.completion: false` drops both the answer and the reasoning.
202
+
203
+ Example id-targeted override (it replaces the whole row, so restate the keys you need):
204
+
205
+ ```yaml
206
+ - insert:
207
+ - id: dsh-observe
208
+ name: dsh-observe
209
+ config:
210
+ enabled: true
211
+ otlp:
212
+ endpoint: http://localhost:4318
213
+ capture:
214
+ tools: false
215
+ sanitize:
216
+ truncatePromptChars: 2000
217
+ batch:
218
+ maxBufferRecords: 20000
219
+ ```
220
+
221
+ ## FAQ
222
+
223
+ <details>
224
+ <summary>Will the raw prompt or tool arguments reach the backend?</summary>
225
+
226
+ Not raw. Every record is sanitized before it is queued, in three layers: structural key names (key/token/secret/password/authorization/credential/apiKey are always in the list, and `sanitize.redactKeys` adds substrings), built-in secret patterns (API keys, GitHub tokens, AWS keys, bearer credentials, private keys) plus your `sanitize.redactPatterns` regexes, and character-budget truncation (prompt/completion 4000 each, tool arguments and results 2000 each, span attributes 512). If you want sizes without bodies, set `llm.prompt` and `llm.completion` to `false` and the records carry only sizes and counts.
227
+
228
+ </details>
229
+
230
+ <details>
231
+ <summary>What happens when a backend is down or the network drops?</summary>
232
+
233
+ Spans and metrics follow the retry → spill chain: a failed batch is retried with deterministic exponential backoff (`retry.maxAttempts` 5 by default, `retry.baseDelayMs × retry.factor`), and once retries are exhausted or the in-memory queue passes `batch.maxQueueRecords` it spills into the bounded durable spool (`batch.maxBufferRecords` 10000 by default, oldest first), drained periodically on `batch.bufferRetryIntervalMs`, so undeliverable batches survive a restart. OTLP metrics are the exception: they are aggregated cumulatively and a lost flush self-heals on the next one.
234
+
235
+ </details>
236
+
237
+ <details>
238
+ <summary>What does the plugin itself store, and where do credentials live?</summary>
239
+
240
+ The offline buffer holds sanitized records only, and records read back from storage are validated again before a sink can see them. The plugin stores no credentials itself: Langfuse public/secret keys appear only in requests to the Langfuse endpoint you configure, and OTLP headers only go to your OTLP endpoint — keep them in credential references or environment-injected values, never in a committed profile patch. It only reads the live event stream and never reads or rewrites session log files.
241
+
242
+ </details>
243
+
244
+ <details>
245
+ <summary>Does it slow the session down?</summary>
246
+
247
+ Collection and sanitization run synchronously in the event handler, but sending is entirely asynchronous: the queue flushes on size or timer, and `session/flush` is only a best-effort kick — the durability checkpoint never waits on a remote backend. Export failures warn, count (`observe.export_failures`), retry, and finally spool; a failing session/event handler is caught and logged, so observability can never break the harness hot path.
248
+
249
+ </details>
250
+
251
+ <details>
252
+ <summary>Does it fight other plugins over services, events, or slots?</summary>
253
+
254
+ It injects one service key (`storageDomain`), listens on three `session/*` events, and registers no model tools, no commands, no client slots, no waterfall listeners, and no global rewrites. The only naming surface worth watching is the optional `observe` remote service (`remote.enabled` is off by default): if another plugin in the same profile takes that service name, enable only one of them.
255
+
256
+ </details>
257
+
258
+ ## Security boundaries
259
+
260
+ - **Off by default** — nothing is captured or exported unless you opt in explicitly (`enabled: true` plus at least one backend).
261
+ - **Sanitize before send** — structural key redaction, built-in secret patterns (API keys, GitHub tokens, AWS keys, bearer credentials, private keys), your patterns, and character budgets all apply before any record leaves memory.
262
+ - **Durable boundary re-validation** — records read back from storage are checked again before a sink can see them.
263
+ - **Failure loud, failure contained** — export failures warn, count, retry, and finally spool; a failing session handler is caught and logged so observability can never break the harness hot path.
264
+ - **Model-visible ⟺ logged** — prompt/completion exports project only the session surface (whose node 0 is the system prompt) and the logged header (call config and tools); the exporter invents no content.
265
+
266
+ ## Permissions & data
267
+
268
+ - **Permissions**: `network:outbound` to the endpoints you configure, `session:read` for the event stream, `storage:write` for the offline buffer; no native code, no filesystem access.
269
+ - **Data**: everything sent is derived from the session log and sanitized (redaction + truncation) before it is queued, buffered, or transmitted. The offline buffer stores only sanitized records, re-validated when read back.
270
+ - **Credentials**: Langfuse public/secret keys travel only to the configured Langfuse endpoint; OTLP headers only to the configured OTLP endpoint. The plugin stores no credentials itself — keep them in credential references or environment-injected values.
271
+
272
+ ## Known limitations
273
+
274
+ - **Baseline `0.2.2-rc.1`** — the plugin is developed and tested against `@deepseek-ai/dsh@0.2.2-rc.1` (devDependencies and CI's primary ruler); `engines.dsh` (`>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`) and the composite peer range keep every published line installable, and older baselines are covered by the second ruler (`typecheck:ci`) plus the compat workflow.
275
+ - **Audit events are not persisted** — the exporter's own `observe/*` records are audit-only: on the current host line the session append gate admits surface events, so no `observe/*` event is written to the session log, and the plugin does not fake one with an unmarked append (that would make sessions unreadable). Treat `observe/status` output (needs `remote.enabled: true`) and the OTLP/Langfuse backends as the audit surface.
276
+ - **Metrics bypass the retry/spool path** — OTLP metrics are aggregated cumulatively, so a lost flush self-heals on the next one (by design, not a bug).
277
+ - **No sampling** — every enabled span family is exported; set `capture.*` switches and `batch.maxBufferRecords` for high-volume sessions.
278
+
279
+ ## Interoperability with other DSH plugins
280
+
281
+ The plugin's registration surface is deliberately narrow, so conflicts are structurally unlikely:
282
+
283
+ - **No tool-name conflict** — it registers no model tools (neither the README nor `src/index.ts` has a tool registration).
284
+ - **No command-name conflict** — it registers no user-facing command, so it never touches the slash-command namespace.
285
+ - **No client-slot conflict** — the package ships no browser half (no `client/` directory), so it registers no client slots.
286
+ - **No waterfall short-circuit** — it only reads `session/event`, `session/flush`, and `session/disposed`; it listens on no allow/passthrough waterfall, so it cannot hold up anyone else's decision.
287
+ - **Its single service key** — `storageDomain` (injected, not provided); plus one **optional** remote service, `observe`, registered only when `remote.enabled: true`.
288
+ - **Outbound traffic only to your endpoints** — OTLP and Langfuse are independent; turning one off does not affect the other.
289
+
290
+ If another observability plugin is installed in the same profile, mind two things: both consume `session/event` (Cordis broadcasts, so neither starves the other) but you get two sets of traces, and do not register the `observe` remote service name twice.
291
+
292
+ ## Compatibility
293
+
294
+ | Surface | Status |
295
+ |---|---|
296
+ | Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (adapted 2026-10-04): session format V4 represents a tool result as a first-class `role: 'tool'` message carrying top-level `toolCallId` + `content` + optional `isError` — the V3 `tool-result` content block is gone from the host's `ContentBlockMap`, and this plugin reads only the V4 shape (a pre-upgrade V3 log still projects through a read-only compatibility path). Session format V3's other traits carry over: the assistant stream is embedded in `assistant/message` / `assistant/attempt`, and the system prompt is surface node 0 (`system/message`); the plugin consumes only the live event stream and never reads session log files. `engines.dsh` is `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0`; the profile install smoke is covered by the compat workflow. |
297
+ | Node | `^22.19.0 \|\| >=24.9.0`, pure ESM (`"type": "module"`) |
298
+ | Backends | OpenTelemetry OTLP/HTTP (traces + metrics, JSON encoding) and Langfuse (LLM observability) — either or both |
299
+ | Model | Model-agnostic: it exports the session/event stream; no model calls are made |
300
+
301
+ Peer dependencies: `@deepseek-ai/cordis ^4.0.5-alpha.1`, `@deepseek-ai/schemastery ^3.18.5`, and `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-storage`, `@deepseek-ai/dsh-storage-domain`, `@deepseek-ai/dsh-storage-json`, `@deepseek-ai/dsh-typert-protocol` (`>=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`; devDependencies pinned to `0.2.2-rc.1`). `zod` is the only runtime dependency, used for durable-boundary validation of the offline buffer.
302
+
303
+ ## Ecosystem & quality
304
+
305
+ - [Gitee mirror](https://gitee.com/perrylink/dsh-observe) (synced mirror; GitHub is authoritative)
306
+ - [dshfind plugin page](https://dshfind.com/plugins/PerryLink/dsh-observe) (installs and ranking)
307
+ - [OpenSSF Scorecard report](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-observe) (driven by [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
308
+ - [dsh-plugin-doctor verification report](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
309
+ - [DSH Market](https://dsh.market/) (listed)
310
+ - **1024 store channel**: run `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-observe` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking)
311
+ - [Ecosystem knowledge base](https://perrylink.github.io/dsh-plugin-guide/): plugin development guide · selection data · maintenance criteria
312
+
313
+ ## Development
314
+
315
+ ```sh
316
+ pnpm install # node ^22.19 || >=24.9
317
+ pnpm run typecheck # tsc: src + tests against the 0.2.2-rc.1 devDeps (no tsconfig paths)
318
+ pnpm run typecheck:ci # tsc against the published line (no paths)
319
+ pnpm run check:ruler-live # canary: must fail to compile, proving the ruler is live (needs the checkout face)
320
+ pnpm test # vitest: 126 tests, 18 suites (real Context/Session/storage seam)
321
+ pnpm run test:coverage # coverage gate (90/80/90/90)
322
+ pnpm run build # tsdown bundle + tsc declarations (lib/)
323
+ pnpm run verify:self-contained # dependency specs resolve from the registry
324
+ pnpm run verify:artifacts # built ESM face + bundle patch present
325
+ node scripts/check-readme-sync.mjs # five-language README sync gate
326
+ pnpm pack # the published tarball
327
+ ```
328
+
329
+ README images are generated by [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Pillow draws the four 1440×576 hero banners; the 1100×660 structure diagram is hand-written SVG), writing `docs/assets/dsh-observe-hero-{zh,en}-{light,dark}.webp` and the `docs/assets/dsh-observe-flow-v5-{light,dark}.svg` pair; rerunning is idempotent. The older `docs/assets/dsh-observe-flow-{light,dark}.svg`, `dsh-observe-flow.svg`, `dsh-observe-hero.png`, and `dsh-observe-demo.{png,gif}` stay in place so existing external links never 404; the READMEs no longer reference them.
330
+
331
+ Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `observability`, `opentelemetry`, `otlp`, `langfuse`, `tracing`
332
+
333
+ ## Family & thanks
334
+
335
+ This project is part of the DeepSeek Harness plugin family maintained by [PerryLink](https://github.com/PerryLink) (all Apache-2.0). If this plugin is useful, **give it a star** — nothing is gated behind it, but it helps the next person find it.
336
+
337
+ - [@PerryLink](https://github.com/PerryLink) — creator and maintainer: collector, pipelines, spool, OTLP/Langfuse sinks, sanitization, and the five-language docs.
338
+
339
+ <details>
340
+ <summary>Expand all plugins</summary>
341
+
342
+ | Plugin | Status |
343
+ |---|---|
344
+ | **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
345
+ | **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
346
+ | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
347
+ | **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 FROZEN — see the repo README |
348
+ | **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
349
+ | **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
350
+ | **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 FROZEN — see the repo README |
351
+ | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
352
+ | **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
353
+ | **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
354
+ | **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
355
+ | **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
356
+ | **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 FROZEN — see the repo README |
357
+ | **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
358
+ | **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
359
+ | **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
360
+ | **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
361
+ | **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
362
+ | **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
363
+ | **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
364
+ | **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
365
+ | **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
366
+ | **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
367
+ | **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
368
+ | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
369
+ | **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
370
+ | **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
371
+ | **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
372
+ | **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
373
+ | **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
374
+ | **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
375
+ | **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
376
+ | **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
377
+ | **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
378
+ | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
379
+ | **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
380
+ | **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
381
+ | **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
382
+ | **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
383
+ | **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
384
+ | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
385
+ | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
386
+ | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
387
+ | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
388
+ | **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
389
+ | **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 FROZEN — see the repo README |
390
+ | **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
391
+ | **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
392
+ | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
393
+ | **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
394
+ | **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
395
+ | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
396
+ | **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
397
+ | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
398
+ | **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
399
+ | **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
400
+ | **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
401
+ | **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 RETIRED (repo archived) |
402
+ | **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
403
+ | **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 RETIRED (repo archived) |
404
+ | **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 RETIRED (repo archived) |
405
+ | **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
406
+ | **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
407
+ | **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
408
+ | **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
409
+ | **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
410
+ | **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
411
+ | **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
412
+ | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
413
+ | **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
414
+ | **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
415
+ | **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
416
+ | **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 FROZEN — see the repo README |
417
+ | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
418
+ | **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
419
+ | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
420
+ | **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
421
+ | **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
422
+ | **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
423
+ | **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
424
+ | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
425
+ | **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
426
+ | **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
427
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
428
+ | **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 RETIRED (repo archived) |
429
+ | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
430
+ | **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
431
+ | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 FROZEN — see the repo README |
432
+ | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 FROZEN — see the repo README |
433
+ | **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 FROZEN — see the repo README |
434
+ | **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 FROZEN — see the repo README |
435
+ | **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 FROZEN — see the repo README |
436
+ | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 RETIRED (repo archived) |
437
+ | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 RETIRED (repo archived) |
438
+ | **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 RETIRED (repo archived) |
439
+
440
+ </details>
441
+
442
+ ## License
443
+
444
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-observe contributors
445
+
446
+ <p align="center"><sub>Apache-2.0 · Community plugin, not affiliated with DeepSeek.</sub></p>