@xiangyixie/dsh-superagent 0.12.0 → 0.14.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.
package/lib/ledger.js CHANGED
@@ -1,270 +1,284 @@
1
- /**
2
- * Append-only spend ledger.
3
- *
4
- * One JSON line per run under `<stateDir>/ledger.jsonl`. Each line is
5
- * self-contained: the unit price that was in effect, the tokens it was applied
6
- * to, and the resulting amount. A later configuration change — even deleting
7
- * the whole price table — cannot rewrite history, because reading the ledger
8
- * never consults the price table.
9
- *
10
- * The ledger is not the source of truth for a run's state; run files are. It is
11
- * a time-series view for "what did the last N days cost", so a missing or
12
- * unreadable line degrades the view instead of breaking a run.
13
- *
14
- * @module dsh-superagent/ledger
15
- */
16
- import fsp from 'node:fs/promises'
17
- import path from 'node:path'
18
- import { TERMINAL_STATUSES } from './store.js'
19
-
20
- const LEDGER_VERSION = 1
21
-
22
- /** Parse a range boundary into epoch milliseconds, or null when unusable. */
23
- function timeOf(value) {
24
- if (value === null || value === undefined || value === '') return null
25
- if (value instanceof Date) {
26
- const ms = value.getTime()
27
- return Number.isFinite(ms) ? ms : null
28
- }
29
- if (typeof value === 'number') return Number.isFinite(value) ? value : null
30
- const parsed = Date.parse(String(value))
31
- return Number.isFinite(parsed) ? parsed : null
32
- }
33
-
34
- /** Fingerprint of what a run's ledger line would record, for idempotence. */
35
- function fingerprintOf(run) {
36
- return [
37
- run.status ?? '',
38
- run.finishedAt ?? '',
39
- run.usage?.modelCalls ?? 0,
40
- run.cost?.totalMicros ?? '',
41
- ].join('|')
42
- }
43
-
44
- /** Total model calls and tokens recorded in one ledger line. */
45
- function lineTotals(entry) {
46
- let calls = 0
47
- let tokens = 0
48
- for (const model of entry.models ?? []) {
49
- calls += Number(model.calls) || 0
50
- tokens += (Number(model.inputTokens) || 0)
51
- + (Number(model.outputTokens) || 0)
52
- + (Number(model.cacheReadTokens) || 0)
53
- }
54
- return { calls, tokens }
55
- }
56
-
57
- /**
58
- * Build a ledger bound to one state root.
59
- *
60
- * @param {string} root - absolute state root (the run store's root).
61
- * @param {{ warn?: (message: string) => void }} [options] - diagnostics sink.
62
- */
63
- export function createLedger(root, options = {}) {
64
- const warn = options.warn ?? (() => {})
65
- const file = path.join(root, 'ledger.jsonl')
66
- /** runId -> fingerprint of the last written line. Loaded on first use. */
67
- let written = null
68
-
69
- async function load() {
70
- if (written) return written
71
- written = new Map()
72
- let text
73
- try {
74
- text = await fsp.readFile(file, 'utf8')
75
- } catch (error) {
76
- if (error?.code !== 'ENOENT') warn(`ledger: cannot read ${file}: ${error?.message ?? error}`)
77
- return written
78
- }
79
- for (const line of text.split('\n')) {
80
- if (!line.trim()) continue
81
- let entry
82
- try {
83
- entry = JSON.parse(line)
84
- } catch {
85
- // A torn tail is what a killed writer leaves behind; the rest of the
86
- // ledger is still valid and must stay readable.
87
- continue
88
- }
89
- if (!entry || typeof entry !== 'object' || typeof entry.runId !== 'string') continue
90
- // Older lines may predate the stored fingerprint; reconstructing it from
91
- // the line itself is enough to avoid appending the same run again.
92
- written.set(entry.runId, entry.fingerprint ?? [
93
- entry.status ?? '',
94
- entry.at ?? '',
95
- entry.calls ?? lineTotals(entry).calls,
96
- entry.totalMicros ?? '',
97
- ].join('|'))
98
- }
99
- return written
100
- }
101
-
102
- /**
103
- * Append one run's spend if it is terminal, priced, and not already recorded.
104
- *
105
- * @param {object} run - run record, as read from the store.
106
- * @returns {Promise<boolean>} true when a line was appended.
107
- */
108
- async function record(run) {
109
- if (!run || typeof run !== 'object' || typeof run.id !== 'string') return false
110
- if (!TERMINAL_STATUSES.has(run.status)) return false
111
- if (!run.usage || !run.usage.modelCalls) return false
112
- const cost = run.cost
113
- // A legacy run priced before per-model records existed has no unit prices
114
- // to store; inventing them would defeat the point of the ledger.
115
- if (!cost || !Array.isArray(cost.records) || cost.records.length === 0) return false
116
-
117
- const known = await load()
118
- const fingerprint = fingerprintOf(run)
119
- if (known.get(run.id) === fingerprint) return false
120
-
121
- const finished = timeOf(run.finishedAt ?? run.updatedAt) ?? Date.now()
122
- const entry = {
123
- v: LEDGER_VERSION,
124
- at: new Date(finished).toISOString(),
125
- runId: run.id,
126
- fingerprint,
127
- status: String(run.status),
128
- calls: run.usage.modelCalls ?? 0,
129
- tokens: run.usage.totalTokens
130
- ?? (run.usage.inputTokens ?? 0) + (run.usage.cacheReadTokens ?? 0) + (run.usage.outputTokens ?? 0),
131
- currency: cost.currency ?? 'USD',
132
- totalMicros: Number.isFinite(cost.totalMicros) ? cost.totalMicros : Math.round((cost.total ?? 0) * 1e6),
133
- total: Number.isFinite(cost.total) ? cost.total : (cost.totalMicros ?? 0) / 1e6,
134
- complete: cost.complete === true,
135
- unpriced: Array.isArray(cost.unpriced) ? [...cost.unpriced] : [],
136
- models: cost.records.map(model => ({
137
- model: String(model.model),
138
- calls: Number(model.calls) || 0,
139
- inputTokens: Number(model.inputTokens) || 0,
140
- outputTokens: Number(model.outputTokens) || 0,
141
- cacheReadTokens: Number(model.cacheReadTokens) || 0,
142
- inputPrice: Number.isFinite(model.inputPrice) ? model.inputPrice : null,
143
- outputPrice: Number.isFinite(model.outputPrice) ? model.outputPrice : null,
144
- cachePrice: Number.isFinite(model.cachePrice) ? model.cachePrice : null,
145
- amountMicros: Number.isFinite(model.amountMicros) ? model.amountMicros : null,
146
- })),
147
- }
148
-
149
- try {
150
- await fsp.mkdir(root, { recursive: true })
151
- await fsp.appendFile(file, `${JSON.stringify(entry)}\n`, 'utf8')
152
- } catch (error) {
153
- warn(`ledger: cannot append to ${file}: ${error?.message ?? error}`)
154
- return false
155
- }
156
- known.set(run.id, fingerprint)
157
- return true
158
- }
159
-
160
- /**
161
- * Read ledger lines in file order, keeping the last line per run.
162
- * @param {{ since?: number | string | Date, until?: number | string | Date }} [range] - time window.
163
- * @returns {Promise<object[]>} entries.
164
- */
165
- async function read(range = {}) {
166
- const since = timeOf(range.since)
167
- const until = timeOf(range.until)
168
- let text
169
- try {
170
- text = await fsp.readFile(file, 'utf8')
171
- } catch (error) {
172
- if (error?.code !== 'ENOENT') warn(`ledger: cannot read ${file}: ${error?.message ?? error}`)
173
- return []
174
- }
175
- const latest = new Map()
176
- for (const line of text.split('\n')) {
177
- if (!line.trim()) continue
178
- let entry
179
- try {
180
- entry = JSON.parse(line)
181
- } catch {
182
- continue
183
- }
184
- if (!entry || typeof entry !== 'object' || typeof entry.runId !== 'string') continue
185
- // Insertion order is preserved on re-set, so the last line for a run is
186
- // also the one that appears last in the returned list.
187
- latest.set(entry.runId, entry)
188
- }
189
- return [...latest.values()].filter(entry => {
190
- const at = timeOf(entry.at)
191
- if (at === null) return false
192
- if (since !== null && at < since) return false
193
- if (until !== null && at > until) return false
194
- return true
195
- })
196
- }
197
-
198
- /**
199
- * Summarise spend over a time range.
200
- *
201
- * Totals are integer micro-units; `total` is only a convenience for callers
202
- * that need a number. `priced` counts runs with at least one priced model,
203
- * and `unpricedRuns` counts runs whose figure is a lower bound.
204
- *
205
- * @param {{ since?: number | string | Date, until?: number | string | Date }} [range] - window.
206
- * @returns {Promise<object>} summary.
207
- */
208
- async function summarize(range = {}) {
209
- const entries = await read(range)
210
- const byModel = {}
211
- let calls = 0
212
- let tokens = 0
213
- let totalMicros = 0
214
- let priced = 0
215
- let unpricedRuns = 0
216
- const currencies = new Set()
217
- let start = null
218
- let end = null
219
- for (const entry of entries) {
220
- const totals = lineTotals(entry)
221
- calls += Number(entry.calls) || totals.calls
222
- tokens += Number(entry.tokens) || totals.tokens
223
- totalMicros += Number(entry.totalMicros) || 0
224
- const models = Array.isArray(entry.models) ? entry.models : []
225
- const hasPriced = models.some(model => Number.isFinite(model.amountMicros))
226
- if (hasPriced) priced += 1
227
- if (entry.complete !== true) unpricedRuns += 1
228
- if (entry.currency) currencies.add(entry.currency)
229
- const at = timeOf(entry.at)
230
- if (at !== null) {
231
- start = start === null ? at : Math.min(start, at)
232
- end = end === null ? at : Math.max(end, at)
233
- }
234
- for (const model of models) {
235
- const target = byModel[model.model] ?? (byModel[model.model] = {
236
- calls: 0,
237
- inputTokens: 0,
238
- outputTokens: 0,
239
- cacheReadTokens: 0,
240
- amountMicros: 0,
241
- priced: false,
242
- })
243
- target.calls += Number(model.calls) || 0
244
- target.inputTokens += Number(model.inputTokens) || 0
245
- target.outputTokens += Number(model.outputTokens) || 0
246
- target.cacheReadTokens += Number(model.cacheReadTokens) || 0
247
- if (Number.isFinite(model.amountMicros)) {
248
- target.amountMicros += model.amountMicros
249
- target.priced = true
250
- }
251
- }
252
- }
253
- return {
254
- runs: entries.length,
255
- priced,
256
- unpricedRuns,
257
- calls,
258
- tokens,
259
- totalMicros,
260
- total: totalMicros / 1e6,
261
- byModel,
262
- currency: currencies.size === 1 ? [...currencies][0] : (currencies.size === 0 ? 'USD' : null),
263
- mixedCurrency: currencies.size > 1,
264
- start,
265
- end,
266
- }
267
- }
268
-
269
- return { file, record, read, summarize }
270
- }
1
+ /**
2
+ * Append-only spend ledger.
3
+ *
4
+ * One JSON line per run under `<stateDir>/ledger.jsonl`. Each line is
5
+ * self-contained: the unit price that was in effect, the tokens it was applied
6
+ * to, and the resulting amount. A later configuration change — even deleting
7
+ * the whole price table — cannot rewrite history, because reading the ledger
8
+ * never consults the price table.
9
+ *
10
+ * The ledger is not the source of truth for a run's state; run files are. It is
11
+ * a time-series view for "what did the last N days cost", so a missing or
12
+ * unreadable line degrades the view instead of breaking a run.
13
+ *
14
+ * @module dsh-superagent/ledger
15
+ */
16
+ import fsp from 'node:fs/promises'
17
+ import path from 'node:path'
18
+ import { addCurrencyMicros, currencyTotals } from './cost.js'
19
+ import { TERMINAL_STATUSES } from './store.js'
20
+
21
+ const LEDGER_VERSION = 1
22
+
23
+ /** Parse a range boundary into epoch milliseconds, or null when unusable. */
24
+ function timeOf(value) {
25
+ if (value === null || value === undefined || value === '') return null
26
+ if (value instanceof Date) {
27
+ const ms = value.getTime()
28
+ return Number.isFinite(ms) ? ms : null
29
+ }
30
+ if (typeof value === 'number') return Number.isFinite(value) ? value : null
31
+ const parsed = Date.parse(String(value))
32
+ return Number.isFinite(parsed) ? parsed : null
33
+ }
34
+
35
+ /** Fingerprint of what a run's ledger line would record, for idempotence. */
36
+ function fingerprintOf(run) {
37
+ return [
38
+ run.status ?? '',
39
+ run.finishedAt ?? '',
40
+ run.usage?.modelCalls ?? 0,
41
+ run.cost?.totalMicros ?? JSON.stringify(run.cost?.byCurrency ?? ''),
42
+ ].join('|')
43
+ }
44
+
45
+ /** Total model calls and tokens recorded in one ledger line. */
46
+ function lineTotals(entry) {
47
+ let calls = 0
48
+ let tokens = 0
49
+ for (const model of entry.models ?? []) {
50
+ calls += Number(model.calls) || 0
51
+ tokens += (Number(model.inputTokens) || 0)
52
+ + (Number(model.outputTokens) || 0)
53
+ + (Number(model.cacheReadTokens) || 0)
54
+ }
55
+ return { calls, tokens }
56
+ }
57
+
58
+ /**
59
+ * Build a ledger bound to one state root.
60
+ *
61
+ * @param {string} root - absolute state root (the run store's root).
62
+ * @param {{ warn?: (message: string) => void }} [options] - diagnostics sink.
63
+ */
64
+ export function createLedger(root, options = {}) {
65
+ const warn = options.warn ?? (() => {})
66
+ const file = path.join(root, 'ledger.jsonl')
67
+ /** runId -> fingerprint of the last written line. Loaded on first use. */
68
+ let written = null
69
+
70
+ async function load() {
71
+ if (written) return written
72
+ written = new Map()
73
+ let text
74
+ try {
75
+ text = await fsp.readFile(file, 'utf8')
76
+ } catch (error) {
77
+ if (error?.code !== 'ENOENT') warn(`ledger: cannot read ${file}: ${error?.message ?? error}`)
78
+ return written
79
+ }
80
+ for (const line of text.split('\n')) {
81
+ if (!line.trim()) continue
82
+ let entry
83
+ try {
84
+ entry = JSON.parse(line)
85
+ } catch {
86
+ // A torn tail is what a killed writer leaves behind; the rest of the
87
+ // ledger is still valid and must stay readable.
88
+ continue
89
+ }
90
+ if (!entry || typeof entry !== 'object' || typeof entry.runId !== 'string') continue
91
+ // Older lines may predate the stored fingerprint; reconstructing it from
92
+ // the line itself is enough to avoid appending the same run again.
93
+ written.set(entry.runId, entry.fingerprint ?? [
94
+ entry.status ?? '',
95
+ entry.at ?? '',
96
+ entry.calls ?? lineTotals(entry).calls,
97
+ entry.totalMicros ?? '',
98
+ ].join('|'))
99
+ }
100
+ return written
101
+ }
102
+
103
+ /**
104
+ * Append one run's spend if it is terminal, priced, and not already recorded.
105
+ *
106
+ * @param {object} run - run record, as read from the store.
107
+ * @returns {Promise<boolean>} true when a line was appended.
108
+ */
109
+ async function record(run) {
110
+ if (!run || typeof run !== 'object' || typeof run.id !== 'string') return false
111
+ if (!TERMINAL_STATUSES.has(run.status)) return false
112
+ if (!run.usage || !run.usage.modelCalls) return false
113
+ const cost = run.cost
114
+ // A legacy run priced before per-model records existed has no unit prices
115
+ // to store; inventing them would defeat the point of the ledger.
116
+ if (!cost || !Array.isArray(cost.records) || cost.records.length === 0) return false
117
+
118
+ const known = await load()
119
+ const fingerprint = fingerprintOf(run)
120
+ if (known.get(run.id) === fingerprint) return false
121
+
122
+ const finished = timeOf(run.finishedAt ?? run.updatedAt) ?? Date.now()
123
+ const entry = {
124
+ v: LEDGER_VERSION,
125
+ at: new Date(finished).toISOString(),
126
+ runId: run.id,
127
+ fingerprint,
128
+ status: String(run.status),
129
+ calls: run.usage.modelCalls ?? 0,
130
+ tokens: run.usage.totalTokens
131
+ ?? (run.usage.inputTokens ?? 0) + (run.usage.cacheReadTokens ?? 0) + (run.usage.outputTokens ?? 0),
132
+ currency: cost.currency ?? (cost.mixedCurrency ? null : 'USD'),
133
+ totalMicros: Number.isFinite(cost.totalMicros)
134
+ ? cost.totalMicros
135
+ : (Number.isFinite(cost.total) ? Math.round(cost.total * 1e6) : null),
136
+ total: Number.isFinite(cost.total) ? cost.total : (Number.isFinite(cost.totalMicros) ? cost.totalMicros / 1e6 : null),
137
+ // A mixed-currency run has no single number; the per-currency amounts
138
+ // travel with the line so a later summary can still add them correctly.
139
+ byCurrency: cost.byCurrency && typeof cost.byCurrency === 'object' ? { ...cost.byCurrency } : {},
140
+ complete: cost.complete === true,
141
+ unpriced: Array.isArray(cost.unpriced) ? [...cost.unpriced] : [],
142
+ models: cost.records.map(model => ({
143
+ model: String(model.model),
144
+ calls: Number(model.calls) || 0,
145
+ inputTokens: Number(model.inputTokens) || 0,
146
+ outputTokens: Number(model.outputTokens) || 0,
147
+ cacheReadTokens: Number(model.cacheReadTokens) || 0,
148
+ inputPrice: Number.isFinite(model.inputPrice) ? model.inputPrice : null,
149
+ outputPrice: Number.isFinite(model.outputPrice) ? model.outputPrice : null,
150
+ cachePrice: Number.isFinite(model.cachePrice) ? model.cachePrice : null,
151
+ amountMicros: Number.isFinite(model.amountMicros) ? model.amountMicros : null,
152
+ })),
153
+ }
154
+
155
+ try {
156
+ await fsp.mkdir(root, { recursive: true })
157
+ await fsp.appendFile(file, `${JSON.stringify(entry)}\n`, 'utf8')
158
+ } catch (error) {
159
+ warn(`ledger: cannot append to ${file}: ${error?.message ?? error}`)
160
+ return false
161
+ }
162
+ known.set(run.id, fingerprint)
163
+ return true
164
+ }
165
+
166
+ /**
167
+ * Read ledger lines in file order, keeping the last line per run.
168
+ * @param {{ since?: number | string | Date, until?: number | string | Date }} [range] - time window.
169
+ * @returns {Promise<object[]>} entries.
170
+ */
171
+ async function read(range = {}) {
172
+ const since = timeOf(range.since)
173
+ const until = timeOf(range.until)
174
+ let text
175
+ try {
176
+ text = await fsp.readFile(file, 'utf8')
177
+ } catch (error) {
178
+ if (error?.code !== 'ENOENT') warn(`ledger: cannot read ${file}: ${error?.message ?? error}`)
179
+ return []
180
+ }
181
+ const latest = new Map()
182
+ for (const line of text.split('\n')) {
183
+ if (!line.trim()) continue
184
+ let entry
185
+ try {
186
+ entry = JSON.parse(line)
187
+ } catch {
188
+ continue
189
+ }
190
+ if (!entry || typeof entry !== 'object' || typeof entry.runId !== 'string') continue
191
+ // Insertion order is preserved on re-set, so the last line for a run is
192
+ // also the one that appears last in the returned list.
193
+ latest.set(entry.runId, entry)
194
+ }
195
+ return [...latest.values()].filter(entry => {
196
+ const at = timeOf(entry.at)
197
+ if (at === null) return false
198
+ if (since !== null && at < since) return false
199
+ if (until !== null && at > until) return false
200
+ return true
201
+ })
202
+ }
203
+
204
+ /**
205
+ * Summarise spend over a time range.
206
+ *
207
+ * Totals are integer micro-units; `total` is only a convenience for callers
208
+ * that need a number. `priced` counts runs with at least one priced model,
209
+ * and `unpricedRuns` counts runs whose figure is a lower bound.
210
+ *
211
+ * @param {{ since?: number | string | Date, until?: number | string | Date }} [range] - window.
212
+ * @returns {Promise<object>} summary.
213
+ */
214
+ async function summarize(range = {}) {
215
+ const entries = await read(range)
216
+ const byModel = {}
217
+ const byCurrency = {}
218
+ let calls = 0
219
+ let tokens = 0
220
+ let priced = 0
221
+ let unpricedRuns = 0
222
+ let start = null
223
+ let end = null
224
+ for (const entry of entries) {
225
+ const totals = lineTotals(entry)
226
+ calls += Number(entry.calls) || totals.calls
227
+ tokens += Number(entry.tokens) || totals.tokens
228
+ // New lines carry the per-currency split. A line written before that
229
+ // field existed has one currency and one total, which is still exact.
230
+ const lineByCurrency = entry.byCurrency && typeof entry.byCurrency === 'object'
231
+ && Object.keys(entry.byCurrency).length > 0
232
+ ? entry.byCurrency
233
+ : (entry.currency ? { [entry.currency]: Number(entry.totalMicros) || 0 } : {})
234
+ for (const [code, micros] of Object.entries(lineByCurrency)) {
235
+ addCurrencyMicros(byCurrency, code, Number(micros) || 0)
236
+ }
237
+ const models = Array.isArray(entry.models) ? entry.models : []
238
+ const hasPriced = models.some(model => Number.isFinite(model.amountMicros))
239
+ if (hasPriced) priced += 1
240
+ if (entry.complete !== true) unpricedRuns += 1
241
+ const at = timeOf(entry.at)
242
+ if (at !== null) {
243
+ start = start === null ? at : Math.min(start, at)
244
+ end = end === null ? at : Math.max(end, at)
245
+ }
246
+ for (const model of models) {
247
+ const target = byModel[model.model] ?? (byModel[model.model] = {
248
+ calls: 0,
249
+ inputTokens: 0,
250
+ outputTokens: 0,
251
+ cacheReadTokens: 0,
252
+ amountMicros: 0,
253
+ priced: false,
254
+ })
255
+ target.calls += Number(model.calls) || 0
256
+ target.inputTokens += Number(model.inputTokens) || 0
257
+ target.outputTokens += Number(model.outputTokens) || 0
258
+ target.cacheReadTokens += Number(model.cacheReadTokens) || 0
259
+ if (Number.isFinite(model.amountMicros)) {
260
+ target.amountMicros += model.amountMicros
261
+ target.priced = true
262
+ }
263
+ }
264
+ }
265
+ const totals = currencyTotals(byCurrency)
266
+ return {
267
+ runs: entries.length,
268
+ priced,
269
+ unpricedRuns,
270
+ calls,
271
+ tokens,
272
+ totalMicros: totals.totalMicros,
273
+ total: totals.total,
274
+ byModel,
275
+ byCurrency,
276
+ currency: totals.currency,
277
+ mixedCurrency: totals.mixedCurrency,
278
+ start,
279
+ end,
280
+ }
281
+ }
282
+
283
+ return { file, record, read, summarize }
284
+ }