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
@@ -0,0 +1,561 @@
1
+ /**
2
+ * The session/event collector: turns the durable session log stream into
3
+ * closed span records and metric samples. Spans open at their boundary
4
+ * events and close at their counterpart events (turn/start → turn/end,
5
+ * step/start → step/end, tool/call → tool/result, request/header →
6
+ * assistant/message); a missing closer (crash, disposal) closes the span
7
+ * with an error status at the latest observed event time. Everything
8
+ * exported is reconstructable from the session log alone — the collector
9
+ * invents no model-visible content, and prompt/completion bodies come from
10
+ * the logged header and the session surface.
11
+ * @module dsh-observe/collector
12
+ */
13
+
14
+ import type { TokenUsage } from '@deepseek-ai/dsh-llm'
15
+ import { isTokenDelta } from '@deepseek-ai/dsh-llm/message'
16
+ import type { EpochHeader, RequestContext, Session, SessionEvent } from '@deepseek-ai/dsh-session'
17
+ import { deriveEventMessage } from '@deepseek-ai/dsh-session'
18
+ import type { ResolvedConfig } from './config.ts'
19
+ import type { JsonScalar, MetricRecord, SpanRecord, TokenCounts } from './model.ts'
20
+ import { findPrice, costUsd } from './pricing.ts'
21
+ import { projectContent, projectMessage } from './project.ts'
22
+ import { sanitizeJsonText, sanitizeText } from './sanitize.ts'
23
+ import type { ObserveLogger } from './sinks.ts'
24
+
25
+ /** Milliseconds → Unix nanoseconds. */
26
+ const NANO = 1_000_000
27
+
28
+ /**
29
+ * The structural surface of the optional `ctx.tokenMeter` service. Only the
30
+ * fields dsh-observe reads are declared; the service is optional, so a host
31
+ * without it simply skips the context-token gauge.
32
+ */
33
+ export interface TokenMeterService {
34
+ measure(session: Session): {
35
+ totalTokens: number
36
+ baseline?: { kind?: string }
37
+ }
38
+ }
39
+
40
+ /** One open tool call awaiting its result. */
41
+ interface ToolSpanState {
42
+ turn: number
43
+ step: number
44
+ name: string
45
+ arguments: string
46
+ startUnixNano: number
47
+ attempt: number
48
+ }
49
+
50
+ /** One open step. */
51
+ interface StepState {
52
+ turn: number
53
+ step: number
54
+ startUnixNano: number
55
+ /** Time of the step's first `request/header` — the LLM span start. */
56
+ requestStartUnixNano: number | undefined
57
+ /** First token-producing stream chunk time. */
58
+ firstChunkUnixNano: number | undefined
59
+ finishReason: string | undefined
60
+ llmClosed: boolean
61
+ /** Sanitized prompt snapshot, captured at `request/header` when enabled. */
62
+ prompt: string | undefined
63
+ /** Occurrence counts of exact (name, arguments) pairs — retry derivation. */
64
+ toolCounts: Map<string, number>
65
+ }
66
+
67
+ /** All live tracking state for one session. */
68
+ interface SessionState {
69
+ turn: { turn: number; startUnixNano: number } | undefined
70
+ step: StepState | undefined
71
+ tools: Map<string, ToolSpanState>
72
+ header: EpochHeader | undefined
73
+ context: RequestContext | undefined
74
+ lastEventUnixNano: number
75
+ }
76
+
77
+ /** Normalize provider usage to the export-facing token counts. */
78
+ function normalizeUsage(usage: TokenUsage | undefined): TokenCounts | undefined {
79
+ if (usage === undefined) return undefined
80
+ return {
81
+ input: usage.inputTokens,
82
+ output: usage.outputTokens,
83
+ cacheRead: usage.cacheReadTokens ?? 0,
84
+ cacheWrite: usage.cacheWriteTokens ?? 0,
85
+ reasoning: usage.reasoningTokens ?? 0,
86
+ }
87
+ }
88
+
89
+ /**
90
+ * The event → span/metric collector. State lives in a WeakMap keyed by the
91
+ * live Session, so sessions the plugin stops seeing are garbage-collected.
92
+ */
93
+ export class Collector {
94
+ private readonly states = new WeakMap<Session, SessionState>()
95
+
96
+ /**
97
+ * @param config - the resolved plugin config.
98
+ * @param tokenMeter - lazy lookup of the optional token meter service.
99
+ * @param onSpan - span sink (both pipelines).
100
+ * @param onMetric - metric sink (OTLP aggregation).
101
+ * @param logger - the plugin logger.
102
+ */
103
+ constructor(
104
+ private readonly config: ResolvedConfig,
105
+ private readonly tokenMeter: () => TokenMeterService | undefined,
106
+ private readonly onSpan: (span: SpanRecord) => void,
107
+ private readonly onMetric: (metric: MetricRecord) => void,
108
+ private readonly logger: ObserveLogger,
109
+ ) {}
110
+
111
+ /**
112
+ * Fold one appended session event.
113
+ * @param session - the session the event belongs to.
114
+ * @param event - the appended event.
115
+ */
116
+ handleEvent(session: Session, event: SessionEvent): void {
117
+ const state = this.stateOf(session)
118
+ state.lastEventUnixNano = event.time * NANO
119
+ switch (event.type) {
120
+ case 'turn/start':
121
+ this.turnStart(session, state, event)
122
+ break
123
+ case 'step/start':
124
+ this.stepStart(session, state, event)
125
+ break
126
+ case 'request/header':
127
+ state.header = event.data.header
128
+ if (this.config.capture.llm
129
+ && this.config.llm.prompt
130
+ && state.step !== undefined
131
+ && state.step.requestStartUnixNano === undefined) {
132
+ state.step.requestStartUnixNano = event.time * NANO
133
+ state.step.prompt = this.capturePrompt(session, event.data.header)
134
+ }
135
+ break
136
+ case 'request/context':
137
+ state.context = event.data
138
+ break
139
+ case 'assistant/chunk':
140
+ if (state.step !== undefined) {
141
+ if (event.data.chunk.type === 'finish') {
142
+ state.step.finishReason = event.data.chunk.reason.kind
143
+ } else if (state.step.firstChunkUnixNano === undefined && isTokenDelta(event.data.chunk)) {
144
+ state.step.firstChunkUnixNano = event.time * NANO
145
+ }
146
+ }
147
+ break
148
+ case 'assistant/message':
149
+ this.assistantMessage(session, state, event)
150
+ break
151
+ case 'tool/call':
152
+ this.toolCall(session, state, event)
153
+ break
154
+ case 'tool/result':
155
+ this.toolResult(session, state, event)
156
+ break
157
+ case 'step/end':
158
+ this.stepEnd(session, state, event)
159
+ break
160
+ case 'turn/end':
161
+ this.turnEnd(session, state, event)
162
+ break
163
+ default:
164
+ // Unknown or plugin-owned session events: nothing to export.
165
+ break
166
+ }
167
+ }
168
+
169
+ /**
170
+ * Close every open span for a session leaving the store.
171
+ * @param session - the disposed session.
172
+ */
173
+ handleSessionDisposed(session: Session): void {
174
+ const state = this.states.get(session)
175
+ if (state === undefined) return
176
+ const end = state.lastEventUnixNano
177
+ if (state.step !== undefined) this.closeStep(session, state, state.step, end, true)
178
+ if (state.turn !== undefined && this.config.capture.turns) {
179
+ const attributes = this.baseAttributes(session, state.turn.turn)
180
+ attributes['turn.reason'] = 'disposed'
181
+ this.onSpan({
182
+ kind: 'turn',
183
+ sessionId: session.id,
184
+ turn: state.turn.turn,
185
+ startUnixNano: state.turn.startUnixNano,
186
+ endUnixNano: end,
187
+ attributes,
188
+ status: 'error',
189
+ })
190
+ }
191
+ this.states.delete(session)
192
+ }
193
+
194
+ private stateOf(session: Session): SessionState {
195
+ const existing = this.states.get(session)
196
+ if (existing !== undefined) return existing
197
+ const state: SessionState = {
198
+ turn: undefined,
199
+ step: undefined,
200
+ tools: new Map(),
201
+ header: undefined,
202
+ context: undefined,
203
+ lastEventUnixNano: Date.now() * NANO,
204
+ }
205
+ this.states.set(session, state)
206
+ return state
207
+ }
208
+
209
+ private turnStart(session: Session, state: SessionState, event: SessionEvent<'turn/start'>): void {
210
+ if (state.step !== undefined) this.closeStep(session, state, state.step, event.time * NANO, true)
211
+ if (state.turn !== undefined && this.config.capture.turns) {
212
+ // The previous turn never closed: close it now so its span cannot leak.
213
+ const attributes = this.baseAttributes(session, state.turn.turn)
214
+ attributes['turn.reason'] = 'aborted'
215
+ this.onSpan({
216
+ kind: 'turn',
217
+ sessionId: session.id,
218
+ turn: state.turn.turn,
219
+ startUnixNano: state.turn.startUnixNano,
220
+ endUnixNano: event.time * NANO,
221
+ attributes,
222
+ status: 'error',
223
+ })
224
+ }
225
+ state.turn = { turn: event.data.turn, startUnixNano: event.time * NANO }
226
+ }
227
+
228
+ private stepStart(session: Session, state: SessionState, event: SessionEvent<'step/start'>): void {
229
+ if (state.step !== undefined) this.closeStep(session, state, state.step, event.time * NANO, true)
230
+ state.step = {
231
+ turn: event.data.turn,
232
+ step: event.data.step,
233
+ startUnixNano: event.time * NANO,
234
+ requestStartUnixNano: undefined,
235
+ firstChunkUnixNano: undefined,
236
+ finishReason: undefined,
237
+ llmClosed: false,
238
+ prompt: undefined,
239
+ toolCounts: new Map(),
240
+ }
241
+ }
242
+
243
+ private assistantMessage(session: Session, state: SessionState, event: SessionEvent<'assistant/message'>): void {
244
+ const step = state.step
245
+ if (step === undefined || step.turn !== event.data.turn || step.step !== event.data.step) {
246
+ this.logger.warn(`session "${session.id}": assistant/message at seq ${event.seq} has no matching open step; llm span skipped`)
247
+ return
248
+ }
249
+ if (this.config.capture.llm) {
250
+ const start = step.requestStartUnixNano ?? step.startUnixNano
251
+ const end = event.time * NANO
252
+ const { provider, model } = this.modelOf(state)
253
+ const usage = normalizeUsage(event.data.usage)
254
+ const price = usage !== undefined && provider !== undefined && model !== undefined
255
+ ? findPrice(this.config.pricing, provider, model)
256
+ : undefined
257
+ const cost = usage !== undefined && price !== undefined ? costUsd(price, usage) : undefined
258
+ const output = this.config.llm.completion
259
+ ? sanitizeText(
260
+ projectContent(event.data.message.content),
261
+ this.config.sanitize.truncateCompletionChars,
262
+ this.config.sanitize,
263
+ )
264
+ : undefined
265
+ this.onSpan({
266
+ kind: 'llm',
267
+ sessionId: session.id,
268
+ turn: step.turn,
269
+ step: step.step,
270
+ startUnixNano: start,
271
+ endUnixNano: end,
272
+ attributes: this.baseAttributes(session, step.turn, step.step),
273
+ status: 'ok',
274
+ llm: {
275
+ ...(this.config.metadata.model && model !== undefined ? { model } : {}),
276
+ ...(this.config.metadata.model && provider !== undefined ? { provider } : {}),
277
+ ...(usage === undefined ? {} : { usage }),
278
+ ...(step.finishReason === undefined ? {} : { finishReason: step.finishReason }),
279
+ ...(step.firstChunkUnixNano === undefined
280
+ ? {}
281
+ : { ttftMs: Math.max(0, Math.round((step.firstChunkUnixNano - start) / NANO)) }),
282
+ ...(step.prompt === undefined ? {} : { input: step.prompt }),
283
+ ...(output === undefined ? {} : { output }),
284
+ ...(cost === undefined ? {} : { costUsd: cost }),
285
+ },
286
+ })
287
+ step.llmClosed = true
288
+ if (usage !== undefined) this.emitUsageMetrics(provider, model, usage, cost)
289
+ }
290
+ }
291
+
292
+ private toolCall(_session: Session, state: SessionState, event: SessionEvent<'tool/call'>): void {
293
+ const step = state.step
294
+ if (step === undefined || step.turn !== event.data.turn || step.step !== event.data.step) return
295
+ if (!this.config.capture.tools) return
296
+ const key = `${event.data.name}\u0000${event.data.arguments}`
297
+ const attempt = (step.toolCounts.get(key) ?? 0) + 1
298
+ step.toolCounts.set(key, attempt)
299
+ state.tools.set(event.data.callId, {
300
+ turn: step.turn,
301
+ step: step.step,
302
+ name: event.data.name,
303
+ arguments: event.data.arguments,
304
+ startUnixNano: event.time * NANO,
305
+ attempt,
306
+ })
307
+ }
308
+
309
+ private toolResult(session: Session, state: SessionState, event: SessionEvent<'tool/result'>): void {
310
+ const callId = event.data.message.source.callId
311
+ const open = state.tools.get(callId)
312
+ if (open === undefined) return
313
+ state.tools.delete(callId)
314
+ const status = event.data.error === undefined ? 'ok' : 'error'
315
+ const attributes = this.baseAttributes(session, open.turn, open.step)
316
+ attributes['tool.status'] = status
317
+ attributes['tool.attempt'] = open.attempt
318
+ attributes['tool.retries'] = open.attempt - 1
319
+ if (event.data.error !== undefined) {
320
+ attributes['tool.error.name'] = this.attr(event.data.error.name)
321
+ attributes['tool.error.code'] = this.attr(event.data.error.code)
322
+ }
323
+ const input = sanitizeJsonText(open.arguments, this.config.sanitize.truncateToolInputChars, this.config.sanitize)
324
+ const output = sanitizeText(
325
+ projectContent(event.data.message.content),
326
+ this.config.sanitize.truncateToolOutputChars,
327
+ this.config.sanitize,
328
+ )
329
+ this.onSpan({
330
+ kind: 'tool',
331
+ sessionId: session.id,
332
+ turn: open.turn,
333
+ step: open.step,
334
+ callId,
335
+ startUnixNano: open.startUnixNano,
336
+ endUnixNano: event.time * NANO,
337
+ attributes,
338
+ status,
339
+ tool: {
340
+ name: open.name,
341
+ status,
342
+ ...(event.data.error === undefined ? {} : {
343
+ errorName: this.attr(event.data.error.name),
344
+ errorCode: this.attr(event.data.error.code),
345
+ }),
346
+ input,
347
+ output,
348
+ attempt: open.attempt,
349
+ retries: open.attempt - 1,
350
+ },
351
+ })
352
+ }
353
+
354
+ private stepEnd(session: Session, state: SessionState, event: SessionEvent<'step/end'>): void {
355
+ const step = state.step
356
+ if (step === undefined || step.turn !== event.data.turn || step.step !== event.data.step) return
357
+ this.closeStep(session, state, step, event.time * NANO, false)
358
+ }
359
+
360
+ private turnEnd(session: Session, state: SessionState, event: SessionEvent<'turn/end'>): void {
361
+ const turn = state.turn
362
+ if (turn === undefined || turn.turn !== event.data.turn) return
363
+ const end = event.time * NANO
364
+ if (state.step !== undefined && state.step.turn === turn.turn) {
365
+ this.closeStep(session, state, state.step, end, true)
366
+ }
367
+ if (this.config.capture.turns) {
368
+ const attributes = this.baseAttributes(session, turn.turn)
369
+ attributes['turn.reason'] = event.data.reason.kind
370
+ if (event.data.reason.kind === 'error') {
371
+ attributes['turn.error.code'] = this.attr(event.data.reason.error.code)
372
+ attributes['turn.error.message'] = this.attr(event.data.reason.error.message)
373
+ } else if (event.data.reason.kind === 'aborted') {
374
+ attributes['turn.cancel.kind'] = event.data.reason.reason.kind
375
+ }
376
+ this.onSpan({
377
+ kind: 'turn',
378
+ sessionId: session.id,
379
+ turn: turn.turn,
380
+ startUnixNano: turn.startUnixNano,
381
+ endUnixNano: end,
382
+ attributes,
383
+ status: event.data.reason.kind === 'error' ? 'error' : 'ok',
384
+ })
385
+ }
386
+ state.turn = undefined
387
+ }
388
+
389
+ /** Close one step: dangling LLM span, dangling tool spans, the step span, and the context gauge. */
390
+ private closeStep(session: Session, state: SessionState, step: StepState, endUnixNano: number, forced: boolean): void {
391
+ if (this.config.capture.llm && !step.llmClosed && step.requestStartUnixNano !== undefined) {
392
+ const attributes = this.baseAttributes(session, step.turn, step.step)
393
+ attributes['observe.incomplete'] = true
394
+ this.onSpan({
395
+ kind: 'llm',
396
+ sessionId: session.id,
397
+ turn: step.turn,
398
+ step: step.step,
399
+ startUnixNano: step.requestStartUnixNano,
400
+ endUnixNano,
401
+ attributes,
402
+ status: 'error',
403
+ llm: {
404
+ ...(step.finishReason === undefined ? {} : { finishReason: step.finishReason }),
405
+ },
406
+ })
407
+ step.llmClosed = true
408
+ }
409
+ for (const [callId, open] of [...state.tools]) {
410
+ if (open.turn !== step.turn || open.step !== step.step) continue
411
+ state.tools.delete(callId)
412
+ const attributes = this.baseAttributes(session, open.turn, open.step)
413
+ attributes['tool.status'] = 'error'
414
+ attributes['tool.attempt'] = open.attempt
415
+ attributes['tool.retries'] = open.attempt - 1
416
+ attributes['tool.error.code'] = 'ABORTED'
417
+ attributes['observe.incomplete'] = true
418
+ this.onSpan({
419
+ kind: 'tool',
420
+ sessionId: session.id,
421
+ turn: open.turn,
422
+ step: open.step,
423
+ callId,
424
+ startUnixNano: open.startUnixNano,
425
+ endUnixNano,
426
+ attributes,
427
+ status: 'error',
428
+ tool: {
429
+ name: open.name,
430
+ status: 'error',
431
+ errorCode: 'ABORTED',
432
+ attempt: open.attempt,
433
+ retries: open.attempt - 1,
434
+ },
435
+ })
436
+ }
437
+ if (this.config.capture.steps) {
438
+ const attributes = this.baseAttributes(session, step.turn, step.step)
439
+ if (forced) attributes['observe.aborted'] = true
440
+ const { provider, model } = this.modelOf(state)
441
+ if (this.config.metadata.model) {
442
+ if (provider !== undefined) attributes.provider = provider
443
+ if (model !== undefined) attributes.model = model
444
+ }
445
+ this.onSpan({
446
+ kind: 'step',
447
+ sessionId: session.id,
448
+ turn: step.turn,
449
+ step: step.step,
450
+ startUnixNano: step.startUnixNano,
451
+ endUnixNano,
452
+ attributes,
453
+ status: 'ok',
454
+ })
455
+ }
456
+ this.emitContextGauge(session, state)
457
+ state.step = undefined
458
+ }
459
+
460
+ /** The context-pressure gauge from the optional token meter (contained). */
461
+ private emitContextGauge(session: Session, state: SessionState): void {
462
+ if (!this.config.metrics.contextTokens) return
463
+ const meter = this.tokenMeter()
464
+ if (meter === undefined) return
465
+ try {
466
+ const measurement = meter.measure(session)
467
+ const attributes: Record<string, string> = {}
468
+ const { provider, model } = this.modelOf(state)
469
+ if (provider !== undefined) attributes.provider = provider
470
+ if (model !== undefined) attributes.model = model
471
+ attributes.baseline = measurement.baseline?.kind ?? 'unknown'
472
+ this.onMetric({
473
+ name: 'observe.context_tokens',
474
+ kind: 'gauge',
475
+ unit: 'tokens',
476
+ value: measurement.totalTokens,
477
+ attributes,
478
+ })
479
+ } catch (error) {
480
+ this.logger.warn(`session "${session.id}": token meter measurement failed: ${error instanceof Error ? error.message : String(error)}`)
481
+ }
482
+ }
483
+
484
+ /** Token and cost counters for one LLM call. */
485
+ private emitUsageMetrics(
486
+ provider: string | undefined,
487
+ model: string | undefined,
488
+ usage: TokenCounts,
489
+ cost: number | undefined,
490
+ ): void {
491
+ if (this.config.metrics.tokens && provider !== undefined && model !== undefined) {
492
+ const kinds: [string, number][] = [
493
+ ['input', usage.input],
494
+ ['output', usage.output],
495
+ ['cache_read', usage.cacheRead],
496
+ ['cache_write', usage.cacheWrite],
497
+ ['reasoning', usage.reasoning],
498
+ ]
499
+ for (const [kind, value] of kinds) {
500
+ if (value > 0) {
501
+ this.onMetric({
502
+ name: 'observe.tokens',
503
+ kind: 'counter',
504
+ unit: 'tokens',
505
+ value,
506
+ attributes: { provider, model, kind },
507
+ })
508
+ }
509
+ }
510
+ }
511
+ if (this.config.metrics.cost && cost !== undefined && provider !== undefined && model !== undefined) {
512
+ this.onMetric({
513
+ name: 'observe.cost',
514
+ kind: 'counter',
515
+ unit: 'USD',
516
+ value: cost,
517
+ attributes: { provider, model },
518
+ })
519
+ }
520
+ }
521
+
522
+ /** The sanitized prompt snapshot: logged system prompt plus the current session surface. */
523
+ private capturePrompt(session: Session, header: EpochHeader | undefined): string {
524
+ const parts: string[] = []
525
+ if (header?.system !== undefined) parts.push(header.system)
526
+ for (const seq of session.surface.nodes) {
527
+ const event = session.events[seq]
528
+ if (event === undefined) continue
529
+ const message = deriveEventMessage(event)
530
+ if (message !== null) parts.push(projectMessage(message))
531
+ }
532
+ return sanitizeText(parts.join('\n'), this.config.sanitize.truncatePromptChars, this.config.sanitize)
533
+ }
534
+
535
+ /** The current provider/model attribution: request context first, then the logged header. */
536
+ private modelOf(state: SessionState): { provider: string | undefined; model: string | undefined } {
537
+ return {
538
+ provider: state.context?.provider ?? state.header?.config.provider,
539
+ model: state.context?.model ?? state.header?.config.model,
540
+ }
541
+ }
542
+
543
+ /** Common span attributes (sanitized and budgeted). */
544
+ private baseAttributes(session: Session, turn: number, step?: number): Record<string, JsonScalar> {
545
+ const attributes: Record<string, JsonScalar> = { turn }
546
+ if (step !== undefined) attributes.step = step
547
+ if (this.config.metadata.sessionId) attributes['session.id'] = session.id
548
+ if (this.config.metadata.cwd && session.header.cwd !== undefined) {
549
+ attributes['session.cwd'] = this.attr(session.header.cwd)
550
+ }
551
+ if (this.config.metadata.agentPreset && session.header.agentPreset !== undefined) {
552
+ attributes['agent.preset'] = this.attr(session.header.agentPreset)
553
+ }
554
+ return attributes
555
+ }
556
+
557
+ /** Sanitize and bound one attribute string. */
558
+ private attr(value: string): string {
559
+ return sanitizeText(value, this.config.sanitize.truncateAttributeChars, this.config.sanitize)
560
+ }
561
+ }