@xiangyixie/dsh-superagent 0.12.0 → 0.12.1

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,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 { 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 { 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
+ }