@xiangyixie/dsh-superagent 0.9.2 → 0.10.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/usage.js CHANGED
@@ -1,152 +1,152 @@
1
- /**
2
- * Token accounting for child sessions.
3
- *
4
- * The subagent seam does not expose usage on a result, but every model call is
5
- * recorded in the child's durable session log. This module reads that log and
6
- * sums the recorded token counts, so a run reports measured numbers instead of
7
- * estimates.
8
- *
9
- * @module dsh-superagent/usage
10
- */
11
- import fsp from 'node:fs/promises'
12
- import path from 'node:path'
13
- import zlib from 'node:zlib'
14
-
15
- const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
16
-
17
- /**
18
- * Decompress every zstd frame in a buffer.
19
- *
20
- * Session logs append one frame per flush, and the one-shot API only decodes
21
- * the first frame, so frames are split on the zstd magic number and decoded
22
- * independently. A slice that fails to decode is counted and skipped.
23
- *
24
- * @param {Buffer} buffer - raw session file.
25
- * @returns {{ text: string, failed: number }} decoded UTF-8 text and failure count.
26
- */
27
- function decodeFrames(buffer) {
28
- if (typeof zlib.zstdDecompressSync !== 'function') return { text: '', failed: 1 }
29
- const starts = []
30
- let at = 0
31
- while ((at = buffer.indexOf(ZSTD_MAGIC, at)) !== -1) {
32
- starts.push(at)
33
- at += ZSTD_MAGIC.length
34
- }
35
- if (starts.length === 0) return { text: '', failed: 1 }
36
- const parts = []
37
- let failed = 0
38
- for (let index = 0; index < starts.length; index++) {
39
- const slice = buffer.subarray(starts[index], starts[index + 1] ?? buffer.length)
40
- try {
41
- parts.push(zlib.zstdDecompressSync(slice).toString('utf8'))
42
- } catch {
43
- failed++
44
- }
45
- }
46
- return { text: parts.join('\n'), failed }
47
- }
48
-
49
- /**
50
- * Sum usage events from one decoded session log.
51
- * @param {string} text - newline-delimited session events.
52
- */
53
- function sumUsage(text) {
54
- const usage = {
55
- inputTokens: 0,
56
- outputTokens: 0,
57
- cacheReadTokens: 0,
58
- totalTokens: 0,
59
- modelCalls: 0,
60
- models: {},
61
- }
62
- for (const line of text.split('\n')) {
63
- if (!line || !line.includes('usage')) continue
64
- let event
65
- try {
66
- event = JSON.parse(line)
67
- } catch {
68
- continue
69
- }
70
- const data = event?.data
71
- const recorded = data?.usage
72
- if (!recorded || typeof recorded !== 'object') continue
73
- const inputTokens = Number(recorded.inputTokens) || 0
74
- const outputTokens = Number(recorded.outputTokens) || 0
75
- if (inputTokens === 0 && outputTokens === 0) continue
76
- usage.inputTokens += inputTokens
77
- usage.outputTokens += outputTokens
78
- usage.cacheReadTokens += Number(recorded.cacheReadTokens) || 0
79
- usage.totalTokens += Number(recorded.totalTokens) || inputTokens + outputTokens
80
- usage.modelCalls++
81
- const source = data?.message?.source
82
- if (source?.kind === 'model') {
83
- const key = `${source.provider ?? '?'}/${source.model ?? '?'}`
84
- const entry = usage.models[key] ?? (usage.models[key] = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, calls: 0 })
85
- entry.inputTokens += inputTokens
86
- entry.outputTokens += outputTokens
87
- entry.cacheReadTokens += Number(recorded.cacheReadTokens) || 0
88
- entry.calls++
89
- }
90
- }
91
- return usage
92
- }
93
-
94
- /**
95
- * Build a reader that maps a child session id to its recorded usage.
96
- *
97
- * @param {object} options - reader options.
98
- * @param {string} options.sessionsRoot - absolute `$DSH_HOME/sessions`.
99
- * @param {(message: string) => void} [options.warn] - diagnostics sink.
100
- * @returns {(childId: string) => Promise<object | null>} usage reader.
101
- */
102
- export function createUsageReader({ sessionsRoot, warn = () => {} }) {
103
- /** @type {Map<string, string>} */
104
- const fileCache = new Map()
105
-
106
- async function locate(childId) {
107
- if (fileCache.has(childId)) return fileCache.get(childId)
108
- let workspaces
109
- try {
110
- workspaces = await fsp.readdir(sessionsRoot, { withFileTypes: true })
111
- } catch {
112
- return null
113
- }
114
- for (const entry of workspaces) {
115
- if (!entry.isDirectory()) continue
116
- // Root sessions live in `session-<id>`; child sessions use the bare id.
117
- for (const folder of [`session-${childId}`, childId]) {
118
- const dir = path.join(sessionsRoot, entry.name, folder)
119
- let names
120
- try {
121
- names = await fsp.readdir(dir)
122
- } catch {
123
- continue
124
- }
125
- const file = names.find(name => name.startsWith('session.') && name.endsWith('.zstd'))
126
- if (!file) continue
127
- const resolved = path.join(dir, file)
128
- fileCache.set(childId, resolved)
129
- return resolved
130
- }
131
- }
132
- return null
133
- }
134
-
135
- return async function readUsage(childId) {
136
- if (!childId) return null
137
- const file = await locate(childId)
138
- if (!file) return null
139
- let buffer
140
- try {
141
- buffer = await fsp.readFile(file)
142
- } catch (error) {
143
- warn(`usage: cannot read session log for ${childId}: ${error?.message ?? error}`)
144
- return null
145
- }
146
- const { text, failed } = decodeFrames(buffer)
147
- if (failed > 0) warn(`usage: ${failed} session frame(s) failed to decode for ${childId}`)
148
- const usage = sumUsage(text)
149
- if (usage.modelCalls === 0) return null
150
- return usage
151
- }
152
- }
1
+ /**
2
+ * Token accounting for child sessions.
3
+ *
4
+ * The subagent seam does not expose usage on a result, but every model call is
5
+ * recorded in the child's durable session log. This module reads that log and
6
+ * sums the recorded token counts, so a run reports measured numbers instead of
7
+ * estimates.
8
+ *
9
+ * @module dsh-superagent/usage
10
+ */
11
+ import fsp from 'node:fs/promises'
12
+ import path from 'node:path'
13
+ import zlib from 'node:zlib'
14
+
15
+ const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
16
+
17
+ /**
18
+ * Decompress every zstd frame in a buffer.
19
+ *
20
+ * Session logs append one frame per flush, and the one-shot API only decodes
21
+ * the first frame, so frames are split on the zstd magic number and decoded
22
+ * independently. A slice that fails to decode is counted and skipped.
23
+ *
24
+ * @param {Buffer} buffer - raw session file.
25
+ * @returns {{ text: string, failed: number }} decoded UTF-8 text and failure count.
26
+ */
27
+ function decodeFrames(buffer) {
28
+ if (typeof zlib.zstdDecompressSync !== 'function') return { text: '', failed: 1 }
29
+ const starts = []
30
+ let at = 0
31
+ while ((at = buffer.indexOf(ZSTD_MAGIC, at)) !== -1) {
32
+ starts.push(at)
33
+ at += ZSTD_MAGIC.length
34
+ }
35
+ if (starts.length === 0) return { text: '', failed: 1 }
36
+ const parts = []
37
+ let failed = 0
38
+ for (let index = 0; index < starts.length; index++) {
39
+ const slice = buffer.subarray(starts[index], starts[index + 1] ?? buffer.length)
40
+ try {
41
+ parts.push(zlib.zstdDecompressSync(slice).toString('utf8'))
42
+ } catch {
43
+ failed++
44
+ }
45
+ }
46
+ return { text: parts.join('\n'), failed }
47
+ }
48
+
49
+ /**
50
+ * Sum usage events from one decoded session log.
51
+ * @param {string} text - newline-delimited session events.
52
+ */
53
+ function sumUsage(text) {
54
+ const usage = {
55
+ inputTokens: 0,
56
+ outputTokens: 0,
57
+ cacheReadTokens: 0,
58
+ totalTokens: 0,
59
+ modelCalls: 0,
60
+ models: {},
61
+ }
62
+ for (const line of text.split('\n')) {
63
+ if (!line || !line.includes('usage')) continue
64
+ let event
65
+ try {
66
+ event = JSON.parse(line)
67
+ } catch {
68
+ continue
69
+ }
70
+ const data = event?.data
71
+ const recorded = data?.usage
72
+ if (!recorded || typeof recorded !== 'object') continue
73
+ const inputTokens = Number(recorded.inputTokens) || 0
74
+ const outputTokens = Number(recorded.outputTokens) || 0
75
+ if (inputTokens === 0 && outputTokens === 0) continue
76
+ usage.inputTokens += inputTokens
77
+ usage.outputTokens += outputTokens
78
+ usage.cacheReadTokens += Number(recorded.cacheReadTokens) || 0
79
+ usage.totalTokens += Number(recorded.totalTokens) || inputTokens + outputTokens
80
+ usage.modelCalls++
81
+ const source = data?.message?.source
82
+ if (source?.kind === 'model') {
83
+ const key = `${source.provider ?? '?'}/${source.model ?? '?'}`
84
+ const entry = usage.models[key] ?? (usage.models[key] = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, calls: 0 })
85
+ entry.inputTokens += inputTokens
86
+ entry.outputTokens += outputTokens
87
+ entry.cacheReadTokens += Number(recorded.cacheReadTokens) || 0
88
+ entry.calls++
89
+ }
90
+ }
91
+ return usage
92
+ }
93
+
94
+ /**
95
+ * Build a reader that maps a child session id to its recorded usage.
96
+ *
97
+ * @param {object} options - reader options.
98
+ * @param {string} options.sessionsRoot - absolute `$DSH_HOME/sessions`.
99
+ * @param {(message: string) => void} [options.warn] - diagnostics sink.
100
+ * @returns {(childId: string) => Promise<object | null>} usage reader.
101
+ */
102
+ export function createUsageReader({ sessionsRoot, warn = () => {} }) {
103
+ /** @type {Map<string, string>} */
104
+ const fileCache = new Map()
105
+
106
+ async function locate(childId) {
107
+ if (fileCache.has(childId)) return fileCache.get(childId)
108
+ let workspaces
109
+ try {
110
+ workspaces = await fsp.readdir(sessionsRoot, { withFileTypes: true })
111
+ } catch {
112
+ return null
113
+ }
114
+ for (const entry of workspaces) {
115
+ if (!entry.isDirectory()) continue
116
+ // Root sessions live in `session-<id>`; child sessions use the bare id.
117
+ for (const folder of [`session-${childId}`, childId]) {
118
+ const dir = path.join(sessionsRoot, entry.name, folder)
119
+ let names
120
+ try {
121
+ names = await fsp.readdir(dir)
122
+ } catch {
123
+ continue
124
+ }
125
+ const file = names.find(name => name.startsWith('session.') && name.endsWith('.zstd'))
126
+ if (!file) continue
127
+ const resolved = path.join(dir, file)
128
+ fileCache.set(childId, resolved)
129
+ return resolved
130
+ }
131
+ }
132
+ return null
133
+ }
134
+
135
+ return async function readUsage(childId) {
136
+ if (!childId) return null
137
+ const file = await locate(childId)
138
+ if (!file) return null
139
+ let buffer
140
+ try {
141
+ buffer = await fsp.readFile(file)
142
+ } catch (error) {
143
+ warn(`usage: cannot read session log for ${childId}: ${error?.message ?? error}`)
144
+ return null
145
+ }
146
+ const { text, failed } = decodeFrames(buffer)
147
+ if (failed > 0) warn(`usage: ${failed} session frame(s) failed to decode for ${childId}`)
148
+ const usage = sumUsage(text)
149
+ if (usage.modelCalls === 0) return null
150
+ return usage
151
+ }
152
+ }