@xiangyixie/dsh-superagent 0.11.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/CHANGELOG.md +97 -10
- package/README.md +322 -28
- package/bin/archive.js +185 -185
- package/bin/doctor.js +84 -84
- package/bin/sync.js +187 -0
- package/bin/workbench.js +98 -0
- package/docs/policy.example.json +38 -0
- package/lib/audit.js +555 -0
- package/lib/cost.js +267 -267
- package/lib/doctor.js +878 -876
- package/lib/guard.js +841 -0
- package/lib/index.js +2031 -1547
- package/lib/inject.js +138 -0
- package/lib/ledger.js +270 -270
- package/lib/memory.js +736 -736
- package/lib/orchestrator.js +3851 -3312
- package/lib/policy.js +739 -0
- package/lib/report.js +1068 -1068
- package/lib/store.js +873 -873
- package/lib/sync.js +456 -0
- package/lib/templates.js +690 -690
- package/lib/watch.js +810 -810
- package/lib/workbench.js +1119 -0
- package/lib/workspace.js +433 -433
- package/package.json +92 -80
- package/public/workbench.html +836 -0
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
|
+
}
|