dsh-observe 0.1.0

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 (92) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/LICENSE +201 -0
  3. package/README.es.md +198 -0
  4. package/README.hi.md +198 -0
  5. package/README.md +198 -0
  6. package/README.pt.md +198 -0
  7. package/README.zh.md +198 -0
  8. package/THIRD_PARTY_NOTICES.md +21 -0
  9. package/cordis.patch.yml +86 -0
  10. package/lib/index.js +1947 -0
  11. package/lib/typert.host.js +109 -0
  12. package/lib/types/backoff.d.ts +17 -0
  13. package/lib/types/backoff.d.ts.map +1 -0
  14. package/lib/types/backoff.js +17 -0
  15. package/lib/types/backoff.js.map +1 -0
  16. package/lib/types/collector.d.ts +83 -0
  17. package/lib/types/collector.d.ts.map +1 -0
  18. package/lib/types/collector.js +506 -0
  19. package/lib/types/collector.js.map +1 -0
  20. package/lib/types/config.d.ts +286 -0
  21. package/lib/types/config.d.ts.map +1 -0
  22. package/lib/types/config.js +312 -0
  23. package/lib/types/config.js.map +1 -0
  24. package/lib/types/ids.d.ts +43 -0
  25. package/lib/types/ids.d.ts.map +1 -0
  26. package/lib/types/ids.js +63 -0
  27. package/lib/types/ids.js.map +1 -0
  28. package/lib/types/index.d.ts +35 -0
  29. package/lib/types/index.d.ts.map +1 -0
  30. package/lib/types/index.js +162 -0
  31. package/lib/types/index.js.map +1 -0
  32. package/lib/types/model.d.ts +89 -0
  33. package/lib/types/model.d.ts.map +1 -0
  34. package/lib/types/model.js +25 -0
  35. package/lib/types/model.js.map +1 -0
  36. package/lib/types/pipeline.d.ts +71 -0
  37. package/lib/types/pipeline.d.ts.map +1 -0
  38. package/lib/types/pipeline.js +193 -0
  39. package/lib/types/pipeline.js.map +1 -0
  40. package/lib/types/pricing.d.ts +34 -0
  41. package/lib/types/pricing.d.ts.map +1 -0
  42. package/lib/types/pricing.js +45 -0
  43. package/lib/types/pricing.js.map +1 -0
  44. package/lib/types/project.d.ts +26 -0
  45. package/lib/types/project.d.ts.map +1 -0
  46. package/lib/types/project.js +52 -0
  47. package/lib/types/project.js.map +1 -0
  48. package/lib/types/remote.d.ts +28 -0
  49. package/lib/types/remote.d.ts.map +1 -0
  50. package/lib/types/remote.js +45 -0
  51. package/lib/types/remote.js.map +1 -0
  52. package/lib/types/sanitize.d.ts +78 -0
  53. package/lib/types/sanitize.d.ts.map +1 -0
  54. package/lib/types/sanitize.js +132 -0
  55. package/lib/types/sanitize.js.map +1 -0
  56. package/lib/types/sinks.d.ts +84 -0
  57. package/lib/types/sinks.d.ts.map +1 -0
  58. package/lib/types/sinks.js +434 -0
  59. package/lib/types/sinks.js.map +1 -0
  60. package/lib/types/spool.d.ts +113 -0
  61. package/lib/types/spool.d.ts.map +1 -0
  62. package/lib/types/spool.js +167 -0
  63. package/lib/types/spool.js.map +1 -0
  64. package/lib/types/typert.host.d.ts +93 -0
  65. package/lib/types/typert.host.d.ts.map +1 -0
  66. package/lib/types/typert.host.js +23 -0
  67. package/lib/types/typert.host.js.map +1 -0
  68. package/lib/types/version.d.ts +10 -0
  69. package/lib/types/version.d.ts.map +1 -0
  70. package/lib/types/version.js +10 -0
  71. package/lib/types/version.js.map +1 -0
  72. package/lib/types/wire.d.ts +206 -0
  73. package/lib/types/wire.d.ts.map +1 -0
  74. package/lib/types/wire.js +71 -0
  75. package/lib/types/wire.js.map +1 -0
  76. package/package.json +147 -0
  77. package/src/backoff.ts +20 -0
  78. package/src/collector.ts +561 -0
  79. package/src/config.ts +604 -0
  80. package/src/ids.ts +68 -0
  81. package/src/index.ts +186 -0
  82. package/src/model.ts +100 -0
  83. package/src/pipeline.ts +205 -0
  84. package/src/pricing.ts +55 -0
  85. package/src/project.ts +55 -0
  86. package/src/remote.ts +56 -0
  87. package/src/sanitize.ts +132 -0
  88. package/src/sinks.ts +471 -0
  89. package/src/spool.ts +196 -0
  90. package/src/typert.host.ts +24 -0
  91. package/src/version.ts +10 -0
  92. package/src/wire.ts +97 -0
package/src/config.ts ADDED
@@ -0,0 +1,604 @@
1
+ /**
2
+ * Config schema and resolution for `dsh-observe`. Every tunable is a
3
+ * validated {@link Config} field changeable from cordis.yml; the resolution
4
+ * step validates numeric bounds, endpoint shapes, and backend credential
5
+ * presence so misconfiguration fails loud at mount — never silently skips
6
+ * or half-enables a backend. The plugin is off unless `enabled: true` AND at
7
+ * least one backend is configured: exporting observability data requires
8
+ * explicit opt-in (privacy default: off).
9
+ * @module dsh-observe/config
10
+ */
11
+
12
+ import z from '@deepseek-ai/schemastery'
13
+
14
+ /** Whether capture of one span family is enabled. */
15
+ export interface CaptureConfig {
16
+ /** Turn lifecycle spans (start/end/reason). */
17
+ turns?: boolean
18
+ /** Step lifecycle spans, parented under their turn. */
19
+ steps?: boolean
20
+ /** Tool-call spans with duration, status, and sanitized arguments/results. */
21
+ tools?: boolean
22
+ /** LLM generation spans with sanitized prompt/completion and usage. */
23
+ llm?: boolean
24
+ }
25
+
26
+ /** Whether and how LLM prompt/completion bodies are captured. */
27
+ export interface LlmCaptureConfig {
28
+ /**
29
+ * Capture the sanitized request prompt (system prompt plus the session
30
+ * surface as of the request). `false` records only sizes and counts.
31
+ */
32
+ prompt?: boolean
33
+ /** Capture the sanitized assistant completion. `false` records only sizes. */
34
+ completion?: boolean
35
+ }
36
+
37
+ /** Metadata capture switches; every one defaults to off except session identity. */
38
+ export interface MetadataCaptureConfig {
39
+ /** Session id (always exported as the trace identity; disabling it removes it from attribute values). */
40
+ sessionId?: boolean
41
+ /** Session working directory. Local path — off by default. */
42
+ cwd?: boolean
43
+ /** Agent preset id the session was composed from, when known. */
44
+ agentPreset?: boolean
45
+ /** Model and provider ids on step/llm/tool attributes. */
46
+ model?: boolean
47
+ }
48
+
49
+ /** Whether each metric family is exported. */
50
+ export interface MetricsCaptureConfig {
51
+ /** Token counters per provider/model from `assistant/message` usage. */
52
+ tokens?: boolean
53
+ /** Cost counter per provider/model when a {@link PricingRule} matches. */
54
+ cost?: boolean
55
+ /** Context-pressure gauge from `ctx.tokenMeter` at step end (needs the service). */
56
+ contextTokens?: boolean
57
+ }
58
+
59
+ /**
60
+ * One pricing rule. A metric is priced by the FIRST rule in list order whose
61
+ * `model` (glob over the model id, e.g. `deepseek-chat`, `*`) and optional
62
+ * `provider` (exact route id) match the usage's attribution. Prices are USD
63
+ * per token. Cache fields are optional: an absent cache price charges cache
64
+ * traffic at the corresponding input price.
65
+ */
66
+ export interface PricingRule {
67
+ /** Exact provider route id, or omitted to match every provider. */
68
+ provider?: string
69
+ /** Glob pattern over the model id; `*` matches any model. */
70
+ model: string
71
+ /** USD per uncached input token. */
72
+ inputPerToken: number
73
+ /** USD per output token. */
74
+ outputPerToken: number
75
+ /** USD per cache-read token; defaults to `inputPerToken` when absent. */
76
+ cacheReadPerToken?: number
77
+ /** USD per cache-write token; defaults to `inputPerToken` when absent. */
78
+ cacheWritePerToken?: number
79
+ }
80
+
81
+ /** The shared sanitization policy applied before any record is queued or spooled. */
82
+ export interface SanitizeConfig {
83
+ /** Master switch; when `false` only truncation applies (no redaction). */
84
+ enabled?: boolean
85
+ /**
86
+ * Key-name substrings (case-insensitive) whose values are replaced with
87
+ * `[REDACTED]` wherever they appear: `key`, `token`, `secret`, `password`,
88
+ * `authorization`, `credential`, `apiKey` are always included.
89
+ */
90
+ redactKeys?: string[]
91
+ /**
92
+ * Additional regular expressions applied to string values; every match is
93
+ * replaced with `[REDACTED]`. Compiled once at mount; an invalid pattern
94
+ * fails the mount loudly. Beware of unbounded patterns (ReDoS): they run
95
+ * over every captured string.
96
+ */
97
+ redactPatterns?: string[]
98
+ /** Prompt character budget (system prompt + surface projection). */
99
+ truncatePromptChars?: number
100
+ /** Completion character budget. */
101
+ truncateCompletionChars?: number
102
+ /** Tool argument character budget. */
103
+ truncateToolInputChars?: number
104
+ /** Tool result character budget. */
105
+ truncateToolOutputChars?: number
106
+ /** Cap on any single span attribute string value. */
107
+ truncateAttributeChars?: number
108
+ }
109
+
110
+ /** The shared batching policy for both backends. */
111
+ export interface BatchConfig {
112
+ /** Flush once the in-memory queue holds this many records. */
113
+ maxRecords?: number
114
+ /** Flush interval in milliseconds when the queue stays below `maxRecords`. */
115
+ flushIntervalMs?: number
116
+ /** Bound on the in-memory queue; excess spills to the offline buffer. */
117
+ maxQueueRecords?: number
118
+ /** Bound on the offline buffer in records; beyond it the oldest record is dropped. */
119
+ maxBufferRecords?: number
120
+ /** How often the offline buffer is retried, in milliseconds. */
121
+ bufferRetryIntervalMs?: number
122
+ }
123
+
124
+ /** The shared retry policy for network exports. */
125
+ export interface RetryConfig {
126
+ /** Attempts per batch, including the first try. */
127
+ maxAttempts?: number
128
+ /** First backoff delay in milliseconds. */
129
+ baseDelayMs?: number
130
+ /** Backoff multiplier per consecutive failure. */
131
+ factor?: number
132
+ /** Upper bound on the computed delay in milliseconds. */
133
+ maxDelayMs?: number
134
+ }
135
+
136
+ /** OpenTelemetry OTLP/HTTP backend (traces + metrics, JSON encoding). */
137
+ export interface OtlpConfig {
138
+ /** Base OTLP/HTTP endpoint, e.g. `http://localhost:4318`; `/v1/traces` and `/v1/metrics` are appended. */
139
+ endpoint: string
140
+ /** `service.name` resource attribute; defaults to `deepseek-harness`. */
141
+ serviceName?: string
142
+ /** `service.version` resource attribute, when set. */
143
+ serviceVersion?: string
144
+ /** Extra headers merged into every export request. */
145
+ headers?: Record<string, string>
146
+ /** Per-request timeout in milliseconds. */
147
+ timeoutMs?: number
148
+ }
149
+
150
+ /** Langfuse backend (LLM observability ingestion). */
151
+ export interface LangfuseConfig {
152
+ /** Langfuse base URL; defaults to the Langfuse Cloud endpoint. */
153
+ baseUrl?: string
154
+ /** Project public key. */
155
+ publicKey: string
156
+ /** Project secret key. */
157
+ secretKey: string
158
+ /** Release tag stamped onto traces. */
159
+ release?: string
160
+ /** Per-request timeout in milliseconds. */
161
+ timeoutMs?: number
162
+ }
163
+
164
+ /** Optional Typert remote service exposing the runtime kill switch to settings pages. */
165
+ export interface RemoteConfig {
166
+ /** Mount the `observe` Typert remote (`observe/status`, `observe/setEnabled`). */
167
+ enabled?: boolean
168
+ }
169
+
170
+ /** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
171
+ export interface Config {
172
+ /** Master switch. Off by default: nothing is exported unless explicitly enabled. */
173
+ enabled?: boolean
174
+ /** OTLP backend; `null`/omitted disables it. */
175
+ otlp?: OtlpConfig | null
176
+ /** Langfuse backend; `null`/omitted disables it. */
177
+ langfuse?: LangfuseConfig | null
178
+ /** Span families to capture. */
179
+ capture?: CaptureConfig
180
+ /** LLM prompt/completion capture policy. */
181
+ llm?: LlmCaptureConfig
182
+ /** Metadata capture switches. */
183
+ metadata?: MetadataCaptureConfig
184
+ /** Metric families to export. */
185
+ metrics?: MetricsCaptureConfig
186
+ /** Pricing table for the cost metric; empty by default (no prices are hardcoded). */
187
+ pricing?: PricingRule[]
188
+ /** Pre-send sanitization policy. */
189
+ sanitize?: SanitizeConfig
190
+ /** Batching policy (shared by both backends). */
191
+ batch?: BatchConfig
192
+ /** Retry/backoff policy (shared by both backends). */
193
+ retry?: RetryConfig
194
+ /** Optional Typert remote surface. */
195
+ remote?: RemoteConfig
196
+ }
197
+
198
+ /** Fully resolved capture policy. */
199
+ export interface ResolvedCapture {
200
+ readonly turns: boolean
201
+ readonly steps: boolean
202
+ readonly tools: boolean
203
+ readonly llm: boolean
204
+ }
205
+
206
+ /** Fully resolved LLM capture policy. */
207
+ export interface ResolvedLlmCapture {
208
+ readonly prompt: boolean
209
+ readonly completion: boolean
210
+ }
211
+
212
+ /** Fully resolved metadata policy. */
213
+ export interface ResolvedMetadata {
214
+ readonly sessionId: boolean
215
+ readonly cwd: boolean
216
+ readonly agentPreset: boolean
217
+ readonly model: boolean
218
+ }
219
+
220
+ /** Fully resolved metric policy. */
221
+ export interface ResolvedMetrics {
222
+ readonly tokens: boolean
223
+ readonly cost: boolean
224
+ readonly contextTokens: boolean
225
+ }
226
+
227
+ /** Fully resolved sanitization policy. */
228
+ export interface ResolvedSanitize {
229
+ readonly enabled: boolean
230
+ readonly redactKeys: readonly string[]
231
+ readonly redactPatterns: readonly RegExp[]
232
+ readonly truncatePromptChars: number
233
+ readonly truncateCompletionChars: number
234
+ readonly truncateToolInputChars: number
235
+ readonly truncateToolOutputChars: number
236
+ readonly truncateAttributeChars: number
237
+ }
238
+
239
+ /** Fully resolved batching policy. */
240
+ export interface ResolvedBatch {
241
+ readonly maxRecords: number
242
+ readonly flushIntervalMs: number
243
+ readonly maxQueueRecords: number
244
+ readonly maxBufferRecords: number
245
+ readonly bufferRetryIntervalMs: number
246
+ }
247
+
248
+ /** Fully resolved retry policy. */
249
+ export interface ResolvedRetry {
250
+ readonly maxAttempts: number
251
+ readonly baseDelayMs: number
252
+ readonly factor: number
253
+ readonly maxDelayMs: number
254
+ }
255
+
256
+ /** Fully resolved OTLP backend. */
257
+ export interface ResolvedOtlp {
258
+ readonly endpoint: string
259
+ readonly serviceName: string
260
+ readonly serviceVersion: string | undefined
261
+ readonly headers: Readonly<Record<string, string>>
262
+ readonly timeoutMs: number
263
+ }
264
+
265
+ /** Fully resolved Langfuse backend. */
266
+ export interface ResolvedLangfuse {
267
+ readonly baseUrl: string
268
+ readonly publicKey: string
269
+ readonly secretKey: string
270
+ readonly release: string | undefined
271
+ readonly timeoutMs: number
272
+ }
273
+
274
+ /** The complete resolved config handed to the runtime. */
275
+ export interface ResolvedConfig {
276
+ readonly enabled: boolean
277
+ readonly otlp: ResolvedOtlp | undefined
278
+ readonly langfuse: ResolvedLangfuse | undefined
279
+ readonly capture: ResolvedCapture
280
+ readonly llm: ResolvedLlmCapture
281
+ readonly metadata: ResolvedMetadata
282
+ readonly metrics: ResolvedMetrics
283
+ readonly pricing: readonly PricingRule[]
284
+ readonly sanitize: ResolvedSanitize
285
+ readonly batch: ResolvedBatch
286
+ readonly retry: ResolvedRetry
287
+ readonly remote: boolean
288
+ }
289
+
290
+ /** Schemastery schema: the loader validates and fills defaults before `apply`. */
291
+ export const Config: z<Config> = z.object({
292
+ enabled: z.boolean().default(false),
293
+ otlp: z.union([z.object({
294
+ endpoint: z.string().required(),
295
+ serviceName: z.string().default('deepseek-harness'),
296
+ serviceVersion: z.string(),
297
+ headers: z.dict(z.string()).default({}),
298
+ timeoutMs: z.number().default(10_000),
299
+ }), z.const(null)]).default(null),
300
+ langfuse: z.union([z.object({
301
+ baseUrl: z.string().default('https://cloud.langfuse.com'),
302
+ publicKey: z.string().required(),
303
+ secretKey: z.string().required(),
304
+ release: z.string(),
305
+ timeoutMs: z.number().default(10_000),
306
+ }), z.const(null)]).default(null),
307
+ capture: z.object({
308
+ turns: z.boolean().default(true),
309
+ steps: z.boolean().default(true),
310
+ tools: z.boolean().default(true),
311
+ llm: z.boolean().default(true),
312
+ }).default({ turns: true, steps: true, tools: true, llm: true }),
313
+ llm: z.object({
314
+ prompt: z.boolean().default(true),
315
+ completion: z.boolean().default(true),
316
+ }).default({ prompt: true, completion: true }),
317
+ metadata: z.object({
318
+ sessionId: z.boolean().default(true),
319
+ cwd: z.boolean().default(false),
320
+ agentPreset: z.boolean().default(true),
321
+ model: z.boolean().default(true),
322
+ }).default({ sessionId: true, cwd: false, agentPreset: true, model: true }),
323
+ metrics: z.object({
324
+ tokens: z.boolean().default(true),
325
+ cost: z.boolean().default(true),
326
+ contextTokens: z.boolean().default(true),
327
+ }).default({ tokens: true, cost: true, contextTokens: true }),
328
+ pricing: z.array(z.object({
329
+ provider: z.string(),
330
+ model: z.string().required(),
331
+ inputPerToken: z.number().required(),
332
+ outputPerToken: z.number().required(),
333
+ cacheReadPerToken: z.number(),
334
+ cacheWritePerToken: z.number(),
335
+ })).default([]),
336
+ sanitize: z.object({
337
+ enabled: z.boolean().default(true),
338
+ redactKeys: z.array(z.string()).default([]),
339
+ redactPatterns: z.array(z.string()).default([]),
340
+ truncatePromptChars: z.number().default(4_000),
341
+ truncateCompletionChars: z.number().default(4_000),
342
+ truncateToolInputChars: z.number().default(2_000),
343
+ truncateToolOutputChars: z.number().default(2_000),
344
+ truncateAttributeChars: z.number().default(512),
345
+ }).default({
346
+ enabled: true,
347
+ redactKeys: [],
348
+ redactPatterns: [],
349
+ truncatePromptChars: 4_000,
350
+ truncateCompletionChars: 4_000,
351
+ truncateToolInputChars: 2_000,
352
+ truncateToolOutputChars: 2_000,
353
+ truncateAttributeChars: 512,
354
+ }),
355
+ batch: z.object({
356
+ maxRecords: z.number().default(256),
357
+ flushIntervalMs: z.number().default(5_000),
358
+ maxQueueRecords: z.number().default(2_000),
359
+ maxBufferRecords: z.number().default(10_000),
360
+ bufferRetryIntervalMs: z.number().default(30_000),
361
+ }).default({
362
+ maxRecords: 256,
363
+ flushIntervalMs: 5_000,
364
+ maxQueueRecords: 2_000,
365
+ maxBufferRecords: 10_000,
366
+ bufferRetryIntervalMs: 30_000,
367
+ }),
368
+ retry: z.object({
369
+ maxAttempts: z.number().default(5),
370
+ baseDelayMs: z.number().default(1_000),
371
+ factor: z.number().default(2),
372
+ maxDelayMs: z.number().default(60_000),
373
+ }).default({ maxAttempts: 5, baseDelayMs: 1_000, factor: 2, maxDelayMs: 60_000 }),
374
+ remote: z.object({
375
+ enabled: z.boolean().default(false),
376
+ }).default({ enabled: false }),
377
+ })
378
+
379
+ /** The redaction key substrings always applied, even with an empty `redactKeys`. */
380
+ const ALWAYS_REDACT_KEYS = ['key', 'token', 'secret', 'password', 'authorization', 'credential'] as const
381
+
382
+ /** Built-in secret patterns applied before the configured `redactPatterns`. */
383
+ const BUILTIN_REDACT_PATTERNS = [
384
+ /\bsk-[A-Za-z0-9]{16,}\b/u,
385
+ /\bghp_[A-Za-z0-9]{20,}\b/u,
386
+ /\bgho_[A-Za-z0-9]{20,}\b/u,
387
+ /\bAKIA[0-9A-Z]{16}\b/u,
388
+ /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/u,
389
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[A-Za-z0-9+/=\s]*-----END [A-Z ]*PRIVATE KEY-----/u,
390
+ ] as const
391
+
392
+ /** Throw unless `value` is a non-negative safe integer. */
393
+ function assertNonNegativeInt(name: string, value: number): void {
394
+ if (!Number.isSafeInteger(value) || value < 0) {
395
+ throw new TypeError(`${name} must be a non-negative safe integer, got ${String(value)}`)
396
+ }
397
+ }
398
+
399
+ /** Throw unless `value` is a positive safe integer. */
400
+ function assertPositiveInt(name: string, value: number): void {
401
+ if (!Number.isSafeInteger(value) || value <= 0) {
402
+ throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`)
403
+ }
404
+ }
405
+
406
+ /** Throw unless `value` is a finite number in `[min, max]`. */
407
+ function assertFiniteRange(name: string, value: number, min: number, max: number): void {
408
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
409
+ throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`)
410
+ }
411
+ }
412
+
413
+ /**
414
+ * Validate an http(s) URL string and normalize it to a clean base (no query,
415
+ * no fragment, no trailing slash).
416
+ * @param name - config key, for the error message.
417
+ * @param value - raw URL value.
418
+ * @returns the normalized base URL.
419
+ */
420
+ export function normalizeBaseUrl(name: string, value: string): string {
421
+ let parsed: URL
422
+ try {
423
+ parsed = new URL(value)
424
+ } catch (error) {
425
+ throw new TypeError(`${name} must be a valid URL, got ${JSON.stringify(value)} (${error instanceof Error ? error.message : 'invalid URL'})`)
426
+ }
427
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
428
+ throw new TypeError(`${name} must use http(s), got ${JSON.stringify(parsed.protocol)}`)
429
+ }
430
+ parsed.search = ''
431
+ parsed.hash = ''
432
+ const text = parsed.href.replace(/\/+$/u, '')
433
+ return text
434
+ }
435
+
436
+ /**
437
+ * Validate raw values and fill explicit defaults. Invalid enums, numeric
438
+ * bounds, endpoints, or credentials throw here — misconfiguration fails loud
439
+ * at mount even when the plugin is mounted without the Schemastery loader.
440
+ * `enabled: true` with no backend also throws: an enabled exporter with
441
+ * nowhere to send is a silent black hole, not a valid configuration.
442
+ * @param config - raw (possibly partial) plugin config.
443
+ * @returns the fully resolved config.
444
+ */
445
+ export function resolveConfig(config: Config = {}): ResolvedConfig {
446
+ const enabled = config.enabled ?? false
447
+
448
+ const otlpRaw = config.otlp ?? null
449
+ const langfuseRaw = config.langfuse ?? null
450
+ if (enabled && otlpRaw === null && langfuseRaw === null) {
451
+ throw new TypeError('enabled: true requires at least one backend (otlp or langfuse)')
452
+ }
453
+
454
+ const otlp: ResolvedOtlp | undefined = otlpRaw === null ? undefined : (() => {
455
+ const endpoint = normalizeBaseUrl('otlp.endpoint', otlpRaw.endpoint)
456
+ if (endpoint.endsWith('/v1/traces') || endpoint.endsWith('/v1/metrics')) {
457
+ throw new TypeError('otlp.endpoint must be the OTLP base URL (e.g. http://localhost:4318); /v1/traces and /v1/metrics are appended')
458
+ }
459
+ if ((otlpRaw.serviceName ?? 'deepseek-harness').trim().length === 0) {
460
+ throw new TypeError('otlp.serviceName must be a non-empty string')
461
+ }
462
+ const timeoutMs = otlpRaw.timeoutMs ?? 10_000
463
+ assertPositiveInt('otlp.timeoutMs', timeoutMs)
464
+ return {
465
+ endpoint,
466
+ serviceName: (otlpRaw.serviceName ?? 'deepseek-harness').trim(),
467
+ serviceVersion: otlpRaw.serviceVersion === undefined ? undefined : otlpRaw.serviceVersion,
468
+ headers: { ...otlpRaw.headers },
469
+ timeoutMs,
470
+ }
471
+ })()
472
+
473
+ const langfuse: ResolvedLangfuse | undefined = langfuseRaw === null ? undefined : (() => {
474
+ const baseUrl = normalizeBaseUrl('langfuse.baseUrl', langfuseRaw.baseUrl ?? 'https://cloud.langfuse.com')
475
+ if (langfuseRaw.publicKey.trim().length === 0) {
476
+ throw new TypeError('langfuse.publicKey must be a non-empty string')
477
+ }
478
+ if (langfuseRaw.secretKey.trim().length === 0) {
479
+ throw new TypeError('langfuse.secretKey must be a non-empty string')
480
+ }
481
+ const timeoutMs = langfuseRaw.timeoutMs ?? 10_000
482
+ assertPositiveInt('langfuse.timeoutMs', timeoutMs)
483
+ return {
484
+ baseUrl,
485
+ publicKey: langfuseRaw.publicKey.trim(),
486
+ secretKey: langfuseRaw.secretKey.trim(),
487
+ release: langfuseRaw.release === undefined ? undefined : langfuseRaw.release,
488
+ timeoutMs,
489
+ }
490
+ })()
491
+
492
+ const captureRaw = config.capture ?? {}
493
+ const llmRaw = config.llm ?? {}
494
+ const metadataRaw = config.metadata ?? {}
495
+ const metricsRaw = config.metrics ?? {}
496
+
497
+ const batchRaw = config.batch ?? {}
498
+ const batch = {
499
+ maxRecords: batchRaw.maxRecords ?? 256,
500
+ flushIntervalMs: batchRaw.flushIntervalMs ?? 5_000,
501
+ maxQueueRecords: batchRaw.maxQueueRecords ?? 2_000,
502
+ maxBufferRecords: batchRaw.maxBufferRecords ?? 10_000,
503
+ bufferRetryIntervalMs: batchRaw.bufferRetryIntervalMs ?? 30_000,
504
+ }
505
+ assertPositiveInt('batch.maxRecords', batch.maxRecords)
506
+ assertPositiveInt('batch.flushIntervalMs', batch.flushIntervalMs)
507
+ assertPositiveInt('batch.maxQueueRecords', batch.maxQueueRecords)
508
+ assertPositiveInt('batch.maxBufferRecords', batch.maxBufferRecords)
509
+ assertPositiveInt('batch.bufferRetryIntervalMs', batch.bufferRetryIntervalMs)
510
+
511
+ const retryRaw = config.retry ?? {}
512
+ const retry = {
513
+ maxAttempts: retryRaw.maxAttempts ?? 5,
514
+ baseDelayMs: retryRaw.baseDelayMs ?? 1_000,
515
+ maxDelayMs: retryRaw.maxDelayMs ?? 60_000,
516
+ }
517
+ assertPositiveInt('retry.maxAttempts', retry.maxAttempts)
518
+ assertPositiveInt('retry.baseDelayMs', retry.baseDelayMs)
519
+ assertPositiveInt('retry.maxDelayMs', retry.maxDelayMs)
520
+ assertFiniteRange('retry.factor', retryRaw.factor ?? 2, 1, 1_000)
521
+
522
+ const sanitizeRaw = config.sanitize ?? {}
523
+ const sanitize = {
524
+ enabled: sanitizeRaw.enabled ?? true,
525
+ redactKeys: [...ALWAYS_REDACT_KEYS, ...(sanitizeRaw.redactKeys ?? [])],
526
+ redactPatterns: compilePatterns([
527
+ ...BUILTIN_REDACT_PATTERNS.map(pattern => pattern.source),
528
+ ...(sanitizeRaw.redactPatterns ?? []),
529
+ ]),
530
+ truncatePromptChars: sanitizeRaw.truncatePromptChars ?? 4_000,
531
+ truncateCompletionChars: sanitizeRaw.truncateCompletionChars ?? 4_000,
532
+ truncateToolInputChars: sanitizeRaw.truncateToolInputChars ?? 2_000,
533
+ truncateToolOutputChars: sanitizeRaw.truncateToolOutputChars ?? 2_000,
534
+ truncateAttributeChars: sanitizeRaw.truncateAttributeChars ?? 512,
535
+ }
536
+ assertNonNegativeInt('sanitize.truncatePromptChars', sanitize.truncatePromptChars)
537
+ assertNonNegativeInt('sanitize.truncateCompletionChars', sanitize.truncateCompletionChars)
538
+ assertNonNegativeInt('sanitize.truncateToolInputChars', sanitize.truncateToolInputChars)
539
+ assertNonNegativeInt('sanitize.truncateToolOutputChars', sanitize.truncateToolOutputChars)
540
+ assertPositiveInt('sanitize.truncateAttributeChars', sanitize.truncateAttributeChars)
541
+
542
+ const pricing = (config.pricing ?? []).map((rule, index) => {
543
+ if (typeof rule.model !== 'string' || rule.model.trim().length === 0) {
544
+ throw new TypeError(`pricing[${index}].model must be a non-empty string`)
545
+ }
546
+ if (typeof rule.inputPerToken !== 'number' || !Number.isFinite(rule.inputPerToken) || rule.inputPerToken < 0) {
547
+ throw new TypeError(`pricing[${index}].inputPerToken must be a non-negative finite number`)
548
+ }
549
+ if (typeof rule.outputPerToken !== 'number' || !Number.isFinite(rule.outputPerToken) || rule.outputPerToken < 0) {
550
+ throw new TypeError(`pricing[${index}].outputPerToken must be a non-negative finite number`)
551
+ }
552
+ return {
553
+ ...(rule.provider === undefined ? {} : { provider: rule.provider }),
554
+ model: rule.model.trim(),
555
+ inputPerToken: rule.inputPerToken,
556
+ outputPerToken: rule.outputPerToken,
557
+ ...(rule.cacheReadPerToken === undefined ? {} : { cacheReadPerToken: rule.cacheReadPerToken }),
558
+ ...(rule.cacheWritePerToken === undefined ? {} : { cacheWritePerToken: rule.cacheWritePerToken }),
559
+ }
560
+ })
561
+
562
+ return {
563
+ enabled,
564
+ otlp,
565
+ langfuse,
566
+ capture: {
567
+ turns: captureRaw.turns ?? true,
568
+ steps: captureRaw.steps ?? true,
569
+ tools: captureRaw.tools ?? true,
570
+ llm: captureRaw.llm ?? true,
571
+ },
572
+ llm: {
573
+ prompt: llmRaw.prompt ?? true,
574
+ completion: llmRaw.completion ?? true,
575
+ },
576
+ metadata: {
577
+ sessionId: metadataRaw.sessionId ?? true,
578
+ cwd: metadataRaw.cwd ?? false,
579
+ agentPreset: metadataRaw.agentPreset ?? true,
580
+ model: metadataRaw.model ?? true,
581
+ },
582
+ metrics: {
583
+ tokens: metricsRaw.tokens ?? true,
584
+ cost: metricsRaw.cost ?? true,
585
+ contextTokens: metricsRaw.contextTokens ?? true,
586
+ },
587
+ pricing,
588
+ sanitize,
589
+ batch,
590
+ retry: { ...retry, factor: retryRaw.factor ?? 2 },
591
+ remote: config.remote?.enabled ?? false,
592
+ }
593
+ }
594
+
595
+ /** Compile user regexes at mount; an invalid pattern fails loud before any export runs. */
596
+ function compilePatterns(patterns: readonly string[]): RegExp[] {
597
+ return patterns.map((pattern, index) => {
598
+ try {
599
+ return new RegExp(pattern, 'gu')
600
+ } catch (error) {
601
+ throw new TypeError(`sanitize.redactPatterns[${index}] is not a valid regular expression: ${error instanceof Error ? error.message : String(error)}`)
602
+ }
603
+ })
604
+ }
package/src/ids.ts ADDED
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Deterministic span and trace ids. Ids are SHA-256 digests of the session
3
+ * identity plus structural keys, truncated to the widths each backend
4
+ * requires (OTel: 16-byte trace ids / 8-byte span ids; Langfuse: 32-hex
5
+ * observation and trace ids). Determinism is a feature: replaying the same
6
+ * session log produces the same ids, so backends deduplicate re-exports
7
+ * instead of double-counting.
8
+ * @module dsh-observe/ids
9
+ */
10
+
11
+ import { createHash } from 'node:crypto'
12
+
13
+ /**
14
+ * Digest joined structural parts to a fixed hex string.
15
+ * @param parts - the structural identity parts.
16
+ * @param bytes - digest length in bytes.
17
+ * @returns lowercase hex, `bytes * 2` characters.
18
+ */
19
+ export function digest(parts: readonly (string | number)[], bytes: number): string {
20
+ const hash = createHash('sha256')
21
+ for (const part of parts) {
22
+ hash.update('|')
23
+ // The runtime type rides the digest: structural parts `1` (number) and
24
+ // `'1'` (string) must never collide into one id.
25
+ hash.update(typeof part)
26
+ hash.update('=')
27
+ hash.update(String(part))
28
+ }
29
+ return hash.digest('hex').slice(0, bytes * 2)
30
+ }
31
+
32
+ /**
33
+ * OTel trace id for one session turn (16 bytes, 32 hex chars).
34
+ * @param sessionId - the session identity.
35
+ * @param turn - the turn number.
36
+ * @returns the trace id.
37
+ */
38
+ export function otelTraceId(sessionId: string, turn: number): string {
39
+ return digest(['trace', sessionId, turn], 16)
40
+ }
41
+
42
+ /**
43
+ * OTel span id for one span (8 bytes, 16 hex chars).
44
+ * @param parts - the span's structural identity.
45
+ * @returns the span id.
46
+ */
47
+ export function otelSpanId(...parts: readonly (string | number)[]): string {
48
+ return digest(['span', ...parts], 8)
49
+ }
50
+
51
+ /**
52
+ * Langfuse trace id for one session turn (32 hex chars).
53
+ * @param sessionId - the session identity.
54
+ * @param turn - the turn number.
55
+ * @returns the trace id.
56
+ */
57
+ export function langfuseTraceId(sessionId: string, turn: number): string {
58
+ return digest(['langfuse-trace', sessionId, turn], 16)
59
+ }
60
+
61
+ /**
62
+ * Langfuse observation or event id (32 hex chars).
63
+ * @param parts - the observation's structural identity.
64
+ * @returns the id.
65
+ */
66
+ export function langfuseId(...parts: readonly (string | number)[]): string {
67
+ return digest(['langfuse', ...parts], 16)
68
+ }