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/index.ts ADDED
@@ -0,0 +1,186 @@
1
+ /**
2
+ * `dsh-observe` — the observability exporter for DeepSeek Harness: turns
3
+ * the `session/event` stream into OTLP/HTTP traces + metrics and Langfuse
4
+ * observations. Turn/step lifecycle spans, tool-call spans (duration,
5
+ * status, derived retries), LLM generation spans with sanitized
6
+ * prompt/completion, and per-model token and cost metrics; async batching,
7
+ * a bounded durable offline buffer (storage-domain), retry with backoff,
8
+ * and a pre-send sanitization layer. Off by default — `enabled: true` plus
9
+ * at least one backend is an explicit opt-in.
10
+ *
11
+ * Function plugin — no default export (the Loader unwraps
12
+ * `exports.default ?? exports`, and a stray default would discard
13
+ * `name`/`inject`/`Config`/`apply`).
14
+ * @module dsh-observe
15
+ */
16
+
17
+ import type { Context } from '@deepseek-ai/cordis'
18
+ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
19
+ import { Config, resolveConfig } from './config.ts'
20
+ import type { ExportRecord, MetricRecord, SpanRecord } from './model.ts'
21
+ import { observeDomainSpec, openSpool } from './spool.ts'
22
+ import { OtlpSink, LangfuseSink } from './sinks.ts'
23
+ import { Pipeline } from './pipeline.ts'
24
+ import { Collector } from './collector.ts'
25
+ import type { TokenMeterService } from './collector.ts'
26
+ import { observeRemotePlugin } from './remote.ts'
27
+ import type { ObserveStatus } from './wire.ts'
28
+
29
+ export const name = 'observe'
30
+ /** The durable offline buffer needs the host's storage-domain facility. */
31
+ export const inject = ['storageDomain']
32
+
33
+ export { Config, resolveConfig } from './config.ts'
34
+ export type { ResolvedConfig, PricingRule, SanitizeConfig, BatchConfig, RetryConfig, OtlpConfig, LangfuseConfig } from './config.ts'
35
+ export { VERSION } from './version.ts'
36
+ export { REDACTED, sanitizeJson, sanitizeJsonText, sanitizeText, truncate } from './sanitize.ts'
37
+ export type { SpanRecord, MetricRecord, ExportRecord, TokenCounts, SpanKind } from './model.ts'
38
+ export type { ObserveStatus, ObserveSetEnabledResult } from './wire.ts'
39
+
40
+ /**
41
+ * Mount the exporter. The resolved config is validated first (fail loud);
42
+ * with `enabled: false` the plugin registers nothing and stays inert.
43
+ * @param ctx - the plugin context (host).
44
+ * @param config - raw plugin config.
45
+ * @returns resolution after the offline-buffer domain is open.
46
+ */
47
+ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
48
+ const resolved = resolveConfig(config)
49
+ const logger = ctx.logger('observe')
50
+ if (!resolved.enabled) {
51
+ logger.info('disabled: enabled is false — no session data is captured or exported')
52
+ return
53
+ }
54
+
55
+ // The runtime kill switch, flippable through the optional Typert remote.
56
+ let enabled = true
57
+ const isEnabled = () => enabled
58
+
59
+ const otlpSink = resolved.otlp === undefined ? undefined : new OtlpSink(resolved.otlp, logger)
60
+ const recordMetric = (metric: MetricRecord): void => {
61
+ if (isEnabled()) otlpSink?.recordMetric(metric)
62
+ }
63
+
64
+ const domain = await ctx.storageDomain.open(observeDomainSpec)
65
+ const spool = openSpool(
66
+ domain,
67
+ resolved.batch.maxBufferRecords,
68
+ count => recordMetric({
69
+ name: 'observe.dropped',
70
+ kind: 'counter',
71
+ unit: 'records',
72
+ value: count,
73
+ attributes: { reason: 'buffer_overflow' },
74
+ }),
75
+ count => {
76
+ logger.warn(`spool: ${count} stored record(s) failed validation and were dropped`)
77
+ },
78
+ )
79
+
80
+ const pipelines: Pipeline[] = []
81
+ if (otlpSink !== undefined) {
82
+ pipelines.push(new Pipeline({
83
+ name: 'otlp',
84
+ sink: otlpSink,
85
+ spool,
86
+ batch: resolved.batch,
87
+ retry: resolved.retry,
88
+ logger,
89
+ isEnabled,
90
+ onMetric: recordMetric,
91
+ }))
92
+ }
93
+ if (resolved.langfuse !== undefined) {
94
+ pipelines.push(new Pipeline({
95
+ name: 'langfuse',
96
+ sink: new LangfuseSink(resolved.langfuse, logger),
97
+ spool,
98
+ batch: resolved.batch,
99
+ retry: resolved.retry,
100
+ logger,
101
+ isEnabled,
102
+ onMetric: recordMetric,
103
+ }))
104
+ }
105
+
106
+ const onSpan = (span: SpanRecord): void => {
107
+ const record: ExportRecord = { kind: 'span', span }
108
+ for (const pipeline of pipelines) pipeline.push(record)
109
+ }
110
+
111
+ const collector = new Collector(
112
+ resolved,
113
+ () => ctx.get('tokenMeter') as unknown as TokenMeterService | undefined,
114
+ onSpan,
115
+ recordMetric,
116
+ logger,
117
+ )
118
+
119
+ // One effect owns every timer and the teardown order: stop the timers,
120
+ // final-flush the pipelines (spilling failures to the durable buffer),
121
+ // then close the domain.
122
+ ctx.effect(() => {
123
+ const timers: ReturnType<typeof setInterval>[] = [
124
+ setInterval(() => {
125
+ for (const pipeline of pipelines) void pipeline.tick()
126
+ }, resolved.batch.flushIntervalMs),
127
+ setInterval(() => {
128
+ for (const pipeline of pipelines) void pipeline.drainSpool()
129
+ }, resolved.batch.bufferRetryIntervalMs),
130
+ ...(otlpSink === undefined
131
+ ? []
132
+ : [setInterval(() => { void otlpSink.flushMetrics() }, resolved.batch.flushIntervalMs)]),
133
+ ]
134
+ return async () => {
135
+ for (const timer of timers) clearInterval(timer)
136
+ await Promise.all(pipelines.map(pipeline => pipeline.dispose()))
137
+ await domain.close()
138
+ }
139
+ })
140
+
141
+ ctx.on('session/event', (session: Session, event: SessionEvent) => {
142
+ try {
143
+ collector.handleEvent(session, event)
144
+ } catch (error) {
145
+ logger.warn(`session "${session.id}": event handling failed: ${error instanceof Error ? error.message : String(error)}`)
146
+ }
147
+ })
148
+
149
+ // Best-effort kick: the session-flush durability checkpoint must not wait
150
+ // on a remote observability backend, so exports run in the background.
151
+ ctx.on('session/flush', () => {
152
+ for (const pipeline of pipelines) pipeline.kick()
153
+ })
154
+
155
+ ctx.on('session/disposed', (session: Session) => {
156
+ try {
157
+ collector.handleSessionDisposed(session)
158
+ } catch (error) {
159
+ logger.warn(`session "${session.id}": disposal handling failed: ${error instanceof Error ? error.message : String(error)}`)
160
+ }
161
+ for (const pipeline of pipelines) pipeline.kick()
162
+ })
163
+
164
+ if (resolved.remote) {
165
+ const depthOf = (backend: 'otlp' | 'langfuse'): number =>
166
+ pipelines.find(pipeline => pipeline.name === backend)?.depth ?? 0
167
+ await ctx.plugin(observeRemotePlugin({
168
+ getStatus: (): ObserveStatus => ({
169
+ enabled,
170
+ backends: {
171
+ otlp: resolved.otlp !== undefined,
172
+ langfuse: resolved.langfuse !== undefined,
173
+ },
174
+ queueDepth: { otlp: depthOf('otlp'), langfuse: depthOf('langfuse') },
175
+ spool: spool.counts(),
176
+ }),
177
+ setEnabled: (value: boolean) => {
178
+ enabled = value
179
+ logger.info(value ? 'exporting re-enabled' : 'exporting disabled (kill switch): new records are dropped until re-enabled')
180
+ if (value) {
181
+ for (const pipeline of pipelines) pipeline.kick()
182
+ }
183
+ },
184
+ }))
185
+ }
186
+ }
package/src/model.ts ADDED
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Owned JSON record model shared by both export backends. Everything here
3
+ * is plain data, already sanitized, and fully detached from live harness
4
+ * objects — records are the only thing that ever crosses the plugin's
5
+ * process boundary, so no Cordis/Session reference can leak into a payload.
6
+ * @module dsh-observe/model
7
+ */
8
+
9
+ /** JSON-scalar attribute values. */
10
+ export type JsonScalar = string | number | boolean
11
+
12
+ /** Normalized token accounting for one LLM call. */
13
+ export interface TokenCounts {
14
+ input: number
15
+ output: number
16
+ cacheRead: number
17
+ cacheWrite: number
18
+ reasoning: number
19
+ }
20
+
21
+ /** Tool-specific span payload (sanitized at capture). */
22
+ export interface ToolSpanInfo {
23
+ name: string
24
+ status: 'ok' | 'error'
25
+ errorName?: string
26
+ errorCode?: string
27
+ input?: string
28
+ output?: string
29
+ /** 1-based occurrence of this exact (name, arguments) pair within the step. */
30
+ attempt: number
31
+ /** `attempt - 1` — earlier identical calls in the same step are retries. */
32
+ retries: number
33
+ }
34
+
35
+ /** LLM-specific span payload (sanitized at capture). */
36
+ export interface LlmSpanInfo {
37
+ model?: string
38
+ provider?: string
39
+ usage?: TokenCounts
40
+ finishReason?: string
41
+ ttftMs?: number
42
+ input?: string
43
+ output?: string
44
+ costUsd?: number
45
+ }
46
+
47
+ /** The span families. */
48
+ export type SpanKind = 'turn' | 'step' | 'tool' | 'llm'
49
+
50
+ /** One closed span, ready for export. */
51
+ export interface SpanRecord {
52
+ kind: SpanKind
53
+ sessionId: string
54
+ turn: number
55
+ /** Present for step/tool/llm spans; absent for turn spans. */
56
+ step?: number
57
+ /** The tool call id (tool spans only) — anchors the deterministic span id. */
58
+ callId?: string
59
+ startUnixNano: number
60
+ endUnixNano: number
61
+ attributes: Record<string, JsonScalar>
62
+ status: 'ok' | 'error'
63
+ tool?: ToolSpanInfo
64
+ llm?: LlmSpanInfo
65
+ }
66
+
67
+ /**
68
+ * One metric sample. Counters carry deltas (the OTLP sink aggregates them
69
+ * into cumulative sums); gauges carry absolute values (last write wins).
70
+ */
71
+ export interface MetricRecord {
72
+ name: string
73
+ kind: 'counter' | 'gauge'
74
+ unit: string
75
+ value: number
76
+ attributes: Record<string, string>
77
+ }
78
+
79
+ /** The record union that flows through pipelines, spool, and sinks. */
80
+ export type ExportRecord =
81
+ | { kind: 'span'; span: SpanRecord }
82
+ | { kind: 'metric'; metric: MetricRecord }
83
+
84
+ /**
85
+ * Validate a value read back from the durable spool: it must look like an
86
+ * export record. The spool is a durable boundary, so hostile or hand-edited
87
+ * values are rejected here instead of reaching a sink.
88
+ * @param value - the stored value.
89
+ * @returns true when the value is an {@link ExportRecord}.
90
+ */
91
+ export function isExportRecord(value: unknown): value is ExportRecord {
92
+ if (typeof value !== 'object' || value === null) return false
93
+ const record = value as { kind?: unknown; span?: unknown; metric?: unknown }
94
+ if (record.kind === 'span') return typeof record.span === 'object' && record.span !== null
95
+ if (record.kind === 'metric') return typeof record.metric === 'object' && record.metric !== null
96
+ return false
97
+ }
98
+
99
+ /** The two export backends. */
100
+ export type BackendName = 'otlp' | 'langfuse'
@@ -0,0 +1,205 @@
1
+ /**
2
+ * The per-backend delivery pipeline: an in-memory queue, periodic and
3
+ * size-triggered flushes, retry with exponential backoff, and spill-over
4
+ * into the durable offline buffer (both when the queue bound is hit and
5
+ * when retries are exhausted). Spool draining runs on its own cycle.
6
+ * @module dsh-observe/pipeline
7
+ */
8
+
9
+ import type { ResolvedBatch, ResolvedRetry } from './config.ts'
10
+ import type { BackendName, ExportRecord, MetricRecord } from './model.ts'
11
+ import { backoffDelayMs } from './backoff.ts'
12
+ import type { ObserveLogger, SpanSink } from './sinks.ts'
13
+ import type { Spool } from './spool.ts'
14
+
15
+ /** Everything one pipeline needs. */
16
+ export interface PipelineOptions {
17
+ name: BackendName
18
+ sink: SpanSink
19
+ spool: Spool
20
+ batch: ResolvedBatch
21
+ retry: ResolvedRetry
22
+ logger: ObserveLogger
23
+ /** The runtime kill switch; when off, pushed records are dropped and counted. */
24
+ isEnabled: () => boolean
25
+ /** Operational metric sink (OTLP aggregation). */
26
+ onMetric: (metric: MetricRecord) => void
27
+ }
28
+
29
+ /**
30
+ * One backend's delivery pipeline. Push is synchronous (the session event
31
+ * hot path); all network work happens on timers or in the background.
32
+ */
33
+ export class Pipeline {
34
+ private queue: ExportRecord[] = []
35
+ private pending: ExportRecord[] | undefined
36
+ private inFlight = false
37
+ private consecutiveFailures = 0
38
+ private retryTimer: ReturnType<typeof setTimeout> | undefined
39
+ private disposed = false
40
+
41
+ /**
42
+ * @param options - the pipeline options (copied, never mutated).
43
+ */
44
+ constructor(private readonly options: PipelineOptions) {}
45
+
46
+ /** Records currently queued or awaiting retry. */
47
+ get depth(): number {
48
+ return this.queue.length + (this.pending?.length ?? 0)
49
+ }
50
+
51
+ /** The backend this pipeline delivers to (`otlp` / `langfuse`). */
52
+ get name(): BackendName {
53
+ return this.options.name
54
+ }
55
+
56
+ /**
57
+ * Queue one record. A disabled runtime drops it (counted); a full queue
58
+ * spills it straight into the durable buffer (bounded; oldest records
59
+ * there are evicted first).
60
+ * @param record - the owned, sanitized record.
61
+ */
62
+ push(record: ExportRecord): void {
63
+ if (this.disposed) return
64
+ if (!this.options.isEnabled()) {
65
+ this.options.onMetric({
66
+ name: 'observe.dropped',
67
+ kind: 'counter',
68
+ unit: 'records',
69
+ value: 1,
70
+ attributes: { reason: 'disabled', backend: this.options.name },
71
+ })
72
+ return
73
+ }
74
+ if (this.queue.length < this.options.batch.maxQueueRecords) {
75
+ this.queue.push(record)
76
+ if (this.queue.length >= this.options.batch.maxRecords) this.kick()
77
+ return
78
+ }
79
+ void this.options.spool.push(this.options.name, [record]).catch((error: unknown) => {
80
+ this.options.logger.warn(`${this.options.name}: buffer spill failed: ${error instanceof Error ? error.message : String(error)}`)
81
+ })
82
+ }
83
+
84
+ /** Start a flush immediately when no flush is already running or scheduled. */
85
+ kick(): void {
86
+ if (this.retryTimer !== undefined || this.inFlight) return
87
+ void this.flushOnce()
88
+ }
89
+
90
+ /** The periodic flush entry point. */
91
+ async tick(): Promise<void> {
92
+ await this.flushOnce()
93
+ }
94
+
95
+ /** One flush attempt: pending retry batch first, otherwise the queue head. */
96
+ private async flushOnce(): Promise<void> {
97
+ if (this.inFlight || this.disposed) return
98
+ const batch = this.pending ?? this.queue.splice(0, this.options.batch.maxRecords)
99
+ if (batch.length === 0) return
100
+ this.inFlight = true
101
+ try {
102
+ await this.options.sink.exportSpans(batch)
103
+ this.consecutiveFailures = 0
104
+ this.pending = undefined
105
+ } catch (error) {
106
+ this.consecutiveFailures += 1
107
+ this.pending = batch
108
+ if (this.consecutiveFailures >= this.options.retry.maxAttempts) {
109
+ this.pending = undefined
110
+ this.consecutiveFailures = 0
111
+ await this.options.spool.push(this.options.name, batch)
112
+ this.options.onMetric({
113
+ name: 'observe.spooled',
114
+ kind: 'counter',
115
+ unit: 'records',
116
+ value: batch.length,
117
+ attributes: { backend: this.options.name },
118
+ })
119
+ } else {
120
+ this.scheduleRetry()
121
+ }
122
+ this.options.onMetric({
123
+ name: 'observe.export_failures',
124
+ kind: 'counter',
125
+ unit: 'requests',
126
+ value: 1,
127
+ attributes: { backend: this.options.name },
128
+ })
129
+ this.options.logger.warn(
130
+ `${this.options.name}: export attempt ${this.consecutiveFailures} failed: ${error instanceof Error ? error.message : String(error)}`,
131
+ )
132
+ } finally {
133
+ this.inFlight = false
134
+ }
135
+ }
136
+
137
+ /** Schedule the backoff retry for the pending batch. */
138
+ private scheduleRetry(): void {
139
+ if (this.disposed || this.retryTimer !== undefined) return
140
+ const delay = backoffDelayMs(this.consecutiveFailures, this.options.retry)
141
+ this.retryTimer = setTimeout(() => {
142
+ this.retryTimer = undefined
143
+ void this.flushOnce()
144
+ }, delay)
145
+ }
146
+
147
+ /**
148
+ * Try the oldest buffered batches once. Batches that fail stay in the
149
+ * buffer for the next cycle; success deletes them.
150
+ */
151
+ async drainSpool(): Promise<void> {
152
+ if (this.inFlight || this.disposed) return
153
+ const { batches, records } = this.options.spool.peek(this.options.name, this.options.batch.maxRecords)
154
+ if (records.length === 0) return
155
+ this.inFlight = true
156
+ try {
157
+ await this.options.sink.exportSpans(records)
158
+ await this.options.spool.remove(batches)
159
+ this.consecutiveFailures = 0
160
+ this.options.onMetric({
161
+ name: 'observe.spool_flushed',
162
+ kind: 'counter',
163
+ unit: 'records',
164
+ value: records.length,
165
+ attributes: { backend: this.options.name },
166
+ })
167
+ } catch (error) {
168
+ this.options.onMetric({
169
+ name: 'observe.export_failures',
170
+ kind: 'counter',
171
+ unit: 'requests',
172
+ value: 1,
173
+ attributes: { backend: this.options.name, kind: 'buffer' },
174
+ })
175
+ this.options.logger.warn(`${this.options.name}: buffer drain failed: ${error instanceof Error ? error.message : String(error)}`)
176
+ } finally {
177
+ this.inFlight = false
178
+ }
179
+ }
180
+
181
+ /**
182
+ * Final flush on unload: one best-effort export of everything queued;
183
+ * whatever fails goes to the durable buffer for the next process run.
184
+ */
185
+ async dispose(): Promise<void> {
186
+ this.disposed = true
187
+ if (this.retryTimer !== undefined) {
188
+ clearTimeout(this.retryTimer)
189
+ this.retryTimer = undefined
190
+ }
191
+ const batch = [...(this.pending ?? []), ...this.queue]
192
+ this.queue = []
193
+ this.pending = undefined
194
+ if (batch.length === 0) return
195
+ try {
196
+ await this.options.sink.exportSpans(batch)
197
+ } catch {
198
+ try {
199
+ await this.options.spool.push(this.options.name, batch)
200
+ } catch (error) {
201
+ this.options.logger.warn(`${this.options.name}: final buffer spill failed: ${error instanceof Error ? error.message : String(error)}`)
202
+ }
203
+ }
204
+ }
205
+ }
package/src/pricing.ts ADDED
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Cost pricing: match a model's token usage against the configured pricing
3
+ * table and compute the call cost. No prices are hardcoded — an empty table
4
+ * simply means the cost metric stays silent for that model.
5
+ * @module dsh-observe/pricing
6
+ */
7
+
8
+ import type { PricingRule } from './config.ts'
9
+ import type { TokenCounts } from './model.ts'
10
+
11
+ /**
12
+ * Compile a glob pattern (only `*` is special) to an anchored regular
13
+ * expression.
14
+ * @param pattern - the glob pattern over a model id.
15
+ * @returns the compiled matcher.
16
+ */
17
+ export function globToRegExp(pattern: string): RegExp {
18
+ const escaped = pattern.replace(/[.+?^${}()|[\]\\]/gu, '\\$&').replaceAll('*', '.*')
19
+ return new RegExp(`^${escaped}$`, 'u')
20
+ }
21
+
22
+ /**
23
+ * Find the first pricing rule matching the attribution: `provider` matches
24
+ * exactly when set, `model` matches as a glob.
25
+ * @param pricing - the configured pricing table, in priority order.
26
+ * @param provider - the provider route id.
27
+ * @param model - the model id.
28
+ * @returns the first matching rule, or undefined.
29
+ */
30
+ export function findPrice(
31
+ pricing: readonly PricingRule[],
32
+ provider: string,
33
+ model: string,
34
+ ): PricingRule | undefined {
35
+ return pricing.find(rule =>
36
+ (rule.provider === undefined || rule.provider === provider)
37
+ && globToRegExp(rule.model).test(model))
38
+ }
39
+
40
+ /**
41
+ * Compute the USD cost of one call under a matched rule. Cache-read and
42
+ * cache-write traffic falls back to the input price when the rule does not
43
+ * price them separately.
44
+ * @param rule - the matched pricing rule.
45
+ * @param usage - the normalized token counts.
46
+ * @returns the cost in USD.
47
+ */
48
+ export function costUsd(rule: PricingRule, usage: TokenCounts): number {
49
+ const cacheRead = usage.cacheRead * (rule.cacheReadPerToken ?? rule.inputPerToken)
50
+ const cacheWrite = usage.cacheWrite * (rule.cacheWritePerToken ?? rule.inputPerToken)
51
+ return usage.input * rule.inputPerToken
52
+ + usage.output * rule.outputPerToken
53
+ + cacheRead
54
+ + cacheWrite
55
+ }
package/src/project.ts ADDED
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Text projection of model-visible messages and content blocks. Used to
3
+ * turn logged messages into the sanitized prompt/completion strings exported
4
+ * to observability backends; every projection stays reconstructable from the
5
+ * session log (the model-visible ⟺ logged invariant holds — no extra
6
+ * information enters the export).
7
+ * @module dsh-observe/project
8
+ */
9
+
10
+ import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
11
+
12
+ /**
13
+ * Project content blocks to one compact plain-text string. Text and
14
+ * reasoning deltas pass through verbatim; tool calls render as
15
+ * `<tool-call name(arguments)>`; images render as `[image]`; tool results
16
+ * recurse. Unknown block types (merge-extensible) are skipped — they carry
17
+ * no projectable text.
18
+ * @param blocks - the model-facing content blocks.
19
+ * @returns the joined projection.
20
+ */
21
+ export function projectContent(blocks: readonly ContentBlock[]): string {
22
+ const parts: string[] = []
23
+ for (const block of blocks) {
24
+ switch (block.type) {
25
+ case 'text':
26
+ parts.push(block.text)
27
+ break
28
+ case 'reasoning':
29
+ parts.push(block.text)
30
+ break
31
+ case 'tool-call':
32
+ parts.push(`<tool-call ${block.name}(${block.arguments})>`)
33
+ break
34
+ case 'image':
35
+ parts.push('[image]')
36
+ break
37
+ case 'tool-result':
38
+ parts.push(projectContent(block.content) + (block.isError === true ? ' [error]' : ''))
39
+ break
40
+ default:
41
+ // Unknown content block types carry no projectable text.
42
+ break
43
+ }
44
+ }
45
+ return parts.join('\n')
46
+ }
47
+
48
+ /**
49
+ * Project one message with its role prefix.
50
+ * @param message - the logged message.
51
+ * @returns `[role] content` on one logical line.
52
+ */
53
+ export function projectMessage(message: Message): string {
54
+ return `[${message.role}] ${projectContent(message.content)}`
55
+ }
package/src/remote.ts ADDED
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The optional Typert remote surface: a small `observe` service exposing
3
+ * `observe/status` and `observe/setEnabled` to settings pages and other
4
+ * remote consumers. `setEnabled` is the runtime kill switch — it stops
5
+ * (or resumes) exporting without unmounting the plugin. Mounted only when
6
+ * `remote.enabled: true`; the service itself never exports data.
7
+ *
8
+ * **No `@Remote` method decorators**: the rc.6 typert loader binds the
9
+ * `./typert` manifest invocations (src/typert.host.ts) to same-named public
10
+ * methods, and decorator syntax breaks both the vitest transform pipeline
11
+ * and the plain-Node build output (the dsh-mcp-panel precedent).
12
+ *
13
+ * @module dsh-observe/remote
14
+ */
15
+
16
+ import type { Context, Plugin } from '@deepseek-ai/cordis'
17
+ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
18
+ import type { ObserveStatus } from './wire.ts'
19
+
20
+ /** Bindings the remote service reads from the runtime. */
21
+ export interface ObserveRemoteOptions {
22
+ getStatus: () => ObserveStatus
23
+ setEnabled: (enabled: boolean) => void
24
+ }
25
+
26
+ /**
27
+ * Build the `observe` Typert remote service as a Cordis plugin class.
28
+ * @param options - the runtime bindings.
29
+ * @returns the service plugin (mount with `ctx.plugin`).
30
+ */
31
+ export function observeRemotePlugin(options: ObserveRemoteOptions): Plugin {
32
+ class ObserveRemoteService extends TypertRemoteService {
33
+ /**
34
+ * @param ctx - the mounting context.
35
+ */
36
+ constructor(ctx: Context) {
37
+ super(ctx, 'observe')
38
+ }
39
+
40
+ /** The read-only status snapshot (bound as `observe/status`). */
41
+ status(): ObserveStatus {
42
+ return options.getStatus()
43
+ }
44
+
45
+ /** The runtime kill switch (bound as `observe/setEnabled`). */
46
+ setEnabled(request: { enabled: boolean }): { enabled: boolean } {
47
+ const value: unknown = request?.enabled
48
+ if (typeof value !== 'boolean') {
49
+ throw new TypeError('observe.setEnabled requires { enabled: boolean }')
50
+ }
51
+ options.setEnabled(value)
52
+ return { enabled: options.getStatus().enabled }
53
+ }
54
+ }
55
+ return ObserveRemoteService as unknown as Plugin
56
+ }