@xiangyixie/dsh-superagent 0.10.0 → 0.12.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/inject.js ADDED
@@ -0,0 +1,138 @@
1
+ /**
2
+ * Live delivery of one instruction into a running child agent.
3
+ *
4
+ * The host has four input boundaries on an Agent: `send`, `followup`, `steer`,
5
+ * and `inject` (dsh-agent `runtime-types.d.ts`). `steer` is the one this module
6
+ * uses: the running driver claims it at its next pre-step, so the message is
7
+ * part of the child's next model request. When a steer arrives after the child
8
+ * already decided to stop, `agent-loop` sees a non-empty next-step inbox and
9
+ * runs one more turn instead of closing (`index.js`, turn loop) — so a live,
10
+ * uncancelled child always consumes it.
11
+ *
12
+ * Two host faces reach that inbox:
13
+ * 1. `subagents.sendMessage(parent, childId, content, { signal })` — the
14
+ * documented, admission-checked path between adjacent Agents. Preferred.
15
+ * 2. `agent.steer(message)` on the live child — the Agent API itself, used
16
+ * only when the service method is absent (a host built without it).
17
+ *
18
+ * Delivery is async: it lands at a step boundary, never in the middle of a
19
+ * model call. The watcher below measures that boundary by polling the child's
20
+ * inbox projection; `INJECT_POLL_MS` is the resolution of every measured
21
+ * figure, so it is reported with the number instead of hidden.
22
+ *
23
+ * @module dsh-superagent/inject
24
+ */
25
+ import { randomUUID } from 'node:crypto'
26
+
27
+ /** Default poll period, in milliseconds, for the inbox claim. */
28
+ export const INJECT_POLL_MS = 25
29
+
30
+ /**
31
+ * The ids still waiting at either inbox boundary of one live child.
32
+ * @param {object | null | undefined} agent - live child Agent.
33
+ * @returns {Set<string>} pending message ids.
34
+ */
35
+ export function pendingIds(agent) {
36
+ const ids = new Set()
37
+ const inbox = agent?.inbox
38
+ for (const list of [inbox?.nextStep, inbox?.nextTurn]) {
39
+ for (const message of list ?? []) {
40
+ if (message?.id !== undefined) ids.add(String(message.id))
41
+ }
42
+ }
43
+ return ids
44
+ }
45
+
46
+ /**
47
+ * Build the host-facing steer function.
48
+ *
49
+ * `subagents` and `agents` are getters, not services, because the subagent
50
+ * service can register after this plugin and can disappear while the host
51
+ * shuts down; reading it at call time keeps both states observable.
52
+ *
53
+ * @param {object} deps - host accessors.
54
+ * @param {() => object | undefined} deps.getSubagents - current subagent service.
55
+ * @param {() => object | undefined} deps.getAgents - current agent registry.
56
+ * @param {(message: string) => void} [deps.log]
57
+ * @returns {(spec: { parent: object, childId: string, text: string, signal?: AbortSignal }) => Promise<{ messageId: string, via: string }>}
58
+ */
59
+ export function createChildSteerer({ getSubagents, getAgents, log = () => {} }) {
60
+ return async function steerChild({ parent, childId, text, signal }) {
61
+ const service = typeof getSubagents === 'function' ? getSubagents() : undefined
62
+ const registry = typeof getAgents === 'function' ? getAgents() : undefined
63
+ const live = registry && typeof registry.get === 'function' ? registry.get(childId) : undefined
64
+ if (!live) {
65
+ const error = new Error(
66
+ `child session ${childId} is no longer live in this host, so no inbox exists to carry the instruction`,
67
+ )
68
+ error.code = 'inject-child-gone'
69
+ throw error
70
+ }
71
+ const content = [{ type: 'text', text }]
72
+ const options = { signal: signal ?? new AbortController().signal }
73
+ if (service && typeof service.sendMessage === 'function') {
74
+ const messageId = await service.sendMessage(parent, childId, content, options)
75
+ return { messageId: String(messageId), via: 'subagents.sendMessage' }
76
+ }
77
+ if (typeof live.steer === 'function') {
78
+ const messageId = `inject-${randomUUID()}`
79
+ live.steer({ id: messageId, role: 'user', content, source: { kind: 'user' } })
80
+ return { messageId, via: 'agent.steer' }
81
+ }
82
+ const error = new Error(
83
+ 'this host exposes no live channel into a running child: neither subagents.sendMessage nor Agent.steer exists',
84
+ )
85
+ error.code = 'inject-unsupported'
86
+ log(`live injection is unsupported by this host: ${error.message}`)
87
+ throw error
88
+ }
89
+ }
90
+
91
+ /**
92
+ * Watch one accepted message until it leaves the child's inbox or the child
93
+ * disappears.
94
+ *
95
+ * Absence from the inbox is the claim signal: the step boundary removes the
96
+ * message before building its model request. The same absence also appears if
97
+ * the activation is cancelled or disposed, so the caller passes that evidence
98
+ * (`onGone`, or a run-level abort check) rather than assuming delivery.
99
+ *
100
+ * @param {object} deps - watcher dependencies.
101
+ * @param {(childId: string) => object | null | undefined} deps.resolveChild - live child lookup.
102
+ * @param {number} [deps.intervalMs] - poll period, defaults to `INJECT_POLL_MS`.
103
+ * @param {() => number} [deps.now] - clock, injectable for tests.
104
+ * @returns {(childId: string, messageId: string, handlers: { onClaimed?: (at: number) => void, onGone?: () => void }) => { stop: () => void, check: () => void }}
105
+ */
106
+ export function createChildWatcher({ resolveChild, intervalMs = INJECT_POLL_MS, now = () => Date.now() }) {
107
+ const period = Math.max(5, Number(intervalMs) || INJECT_POLL_MS)
108
+ return function watch(childId, messageId, handlers = {}) {
109
+ let timer = null
110
+ let stopped = false
111
+ const stop = () => {
112
+ if (stopped) return
113
+ stopped = true
114
+ if (timer) clearInterval(timer)
115
+ timer = null
116
+ }
117
+ const check = () => {
118
+ if (stopped) return
119
+ let agent = null
120
+ try {
121
+ agent = resolveChild(childId)
122
+ } catch {
123
+ agent = null
124
+ }
125
+ if (!agent) {
126
+ stop()
127
+ handlers.onGone?.()
128
+ return
129
+ }
130
+ if (pendingIds(agent).has(String(messageId))) return
131
+ stop()
132
+ handlers.onClaimed?.(now())
133
+ }
134
+ timer = setInterval(check, period)
135
+ timer.unref?.()
136
+ return { stop, check }
137
+ }
138
+ }
package/lib/ledger.js ADDED
@@ -0,0 +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
+ }