dsh-token-usage-ledger 0.0.0-stage → 0.0.36
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 +1067 -0
- package/LICENSE +21 -0
- package/README.md +237 -2
- package/cordis.patch.yml +30 -0
- package/lib/client.js +4469 -0
- package/lib/host/aggregate.d.ts +132 -0
- package/lib/host/aggregate.js +840 -0
- package/lib/host/api.d.ts +118 -0
- package/lib/host/api.js +346 -0
- package/lib/host/backfill.d.ts +54 -0
- package/lib/host/backfill.js +265 -0
- package/lib/host/collector.d.ts +139 -0
- package/lib/host/collector.js +441 -0
- package/lib/host/ledger-io.d.ts +125 -0
- package/lib/host/ledger-io.js +211 -0
- package/lib/host/operation-error.d.ts +22 -0
- package/lib/host/operation-error.js +28 -0
- package/lib/host/paths.d.ts +35 -0
- package/lib/host/paths.js +63 -0
- package/lib/host/pricing-module.d.ts +112 -0
- package/lib/host/pricing-module.js +63 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.d.ts +31 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.js +67 -0
- package/lib/host/pricing-modules/index.d.ts +27 -0
- package/lib/host/pricing-modules/index.js +30 -0
- package/lib/host/pricing.d.ts +192 -0
- package/lib/host/pricing.js +287 -0
- package/lib/host/records.d.ts +47 -0
- package/lib/host/records.js +116 -0
- package/lib/host/runtime-marker.d.ts +67 -0
- package/lib/host/runtime-marker.js +71 -0
- package/lib/host/schema.d.ts +77 -0
- package/lib/host/schema.js +158 -0
- package/lib/host/store.d.ts +171 -0
- package/lib/host/store.js +337 -0
- package/lib/host/workspace-titles.d.ts +38 -0
- package/lib/host/workspace-titles.js +136 -0
- package/lib/host/zstd.d.ts +41 -0
- package/lib/host/zstd.js +134 -0
- package/lib/index.d.ts +82 -0
- package/lib/index.js +512 -0
- package/lib/shared/format.d.ts +415 -0
- package/lib/shared/format.js +714 -0
- package/lib/shared/protocol.d.ts +646 -0
- package/lib/shared/protocol.js +129 -0
- package/package.json +85 -4
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* dsh-token-usage-ledger — Host half.
|
|
3
|
+
*
|
|
4
|
+
* Records one ledger line per completed Turn and serves the read-only JSON
|
|
5
|
+
* summary the dashboard reads. The whole design is organised around one
|
|
6
|
+
* constraint: **this plugin must not be able to affect a conversation**.
|
|
7
|
+
*
|
|
8
|
+
* - It observes through `session/event`, which the Session store documents as a
|
|
9
|
+
* post-commit, fire-and-forget feed whose listener failures are logged and
|
|
10
|
+
* contained — a throwing observer cannot fail the append that produced it.
|
|
11
|
+
* - It reacts to `turn/end`, the moment the Turn is already committed and the
|
|
12
|
+
* conversation is no longer mid-flight.
|
|
13
|
+
* - It performs NO I/O inside that dispatch: the record is built from scalars
|
|
14
|
+
* the collector already holds and pushed onto a queue that a `setImmediate`
|
|
15
|
+
* drain appends later.
|
|
16
|
+
* - Every entry point is wrapped, and the plugin exports no `Config` schema, so
|
|
17
|
+
* it also has no runtime dependency on any `@deepseek-ai/*` package: a broken
|
|
18
|
+
* ledger degrades to a health counter in the dashboard, never to a failed
|
|
19
|
+
* Turn.
|
|
20
|
+
*
|
|
21
|
+
* @module dsh-token-usage-ledger
|
|
22
|
+
*/
|
|
23
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
24
|
+
import { type ModelPrices } from './host/pricing.js';
|
|
25
|
+
import type { Currency } from './shared/protocol.js';
|
|
26
|
+
/** Plugin id; matches the `id` used by this package's Cordis patch row. */
|
|
27
|
+
export declare const name = "token-usage";
|
|
28
|
+
/**
|
|
29
|
+
* Plugin version, kept in sync with `package.json` by
|
|
30
|
+
* `tests/manifest.test.mjs`.
|
|
31
|
+
*/
|
|
32
|
+
export declare const PLUGIN_VERSION = "0.0.36";
|
|
33
|
+
/** Settings after normalization; every field has a usable default. */
|
|
34
|
+
export interface PluginSettings {
|
|
35
|
+
/** Ledger directory; `undefined` means `<dsh home>/token-usage`. */
|
|
36
|
+
dataDir: string | undefined;
|
|
37
|
+
/**
|
|
38
|
+
* Id of the price era to price with (`config.pricingModule`).
|
|
39
|
+
*
|
|
40
|
+
* `''` means "the newest era this build carries". Naming an era explicit is
|
|
41
|
+
* how a deployment pins itself to a known price list, or rolls back.
|
|
42
|
+
*/
|
|
43
|
+
pricingModule: string;
|
|
44
|
+
/** Currency to price in. */
|
|
45
|
+
currency: Currency;
|
|
46
|
+
/** Multiplier applied outside peak hours. */
|
|
47
|
+
offPeakRatio: number;
|
|
48
|
+
/** Pricing-timezone offset from UTC in minutes. */
|
|
49
|
+
peakOffsetMinutes: number;
|
|
50
|
+
/** Model id priced in place of an unknown one. */
|
|
51
|
+
fallbackModel: string;
|
|
52
|
+
/** Peak-hour price overrides/additions, per one million tokens. */
|
|
53
|
+
models: Record<string, ModelPrices>;
|
|
54
|
+
/** Route prefix for the summary endpoint. */
|
|
55
|
+
apiPath: string;
|
|
56
|
+
/** Additional accepted `Host` values beyond loopback. */
|
|
57
|
+
extraAllowedHosts: string[];
|
|
58
|
+
/** Accept any `Host`; disables the anti-DNS-rebinding control. */
|
|
59
|
+
allowAnyHost: boolean;
|
|
60
|
+
/** Ledger write-queue bound. */
|
|
61
|
+
maxPendingWrites: number;
|
|
62
|
+
/** Emit verbose diagnostics. */
|
|
63
|
+
debug: boolean;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Normalize a raw Cordis row config into usable settings.
|
|
67
|
+
*
|
|
68
|
+
* Never throws: an unusable value falls back to its default so a typo in
|
|
69
|
+
* `cordis.patch.yml` cannot stop the plugin from loading, let alone the
|
|
70
|
+
* conversation from running.
|
|
71
|
+
*
|
|
72
|
+
* @param raw - config object supplied by the loader, possibly undefined or malformed.
|
|
73
|
+
* @returns complete settings.
|
|
74
|
+
*/
|
|
75
|
+
export declare function normalizeSettings(raw: unknown): PluginSettings;
|
|
76
|
+
/**
|
|
77
|
+
* Plugin body.
|
|
78
|
+
*
|
|
79
|
+
* @param ctx - this plugin row's Cordis context; every side effect hangs off it.
|
|
80
|
+
* @param rawConfig - the row's `config` block, unvalidated by design.
|
|
81
|
+
*/
|
|
82
|
+
export declare function apply(ctx: Context, rawConfig?: unknown): void;
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* dsh-token-usage-ledger — Host half.
|
|
3
|
+
*
|
|
4
|
+
* Records one ledger line per completed Turn and serves the read-only JSON
|
|
5
|
+
* summary the dashboard reads. The whole design is organised around one
|
|
6
|
+
* constraint: **this plugin must not be able to affect a conversation**.
|
|
7
|
+
*
|
|
8
|
+
* - It observes through `session/event`, which the Session store documents as a
|
|
9
|
+
* post-commit, fire-and-forget feed whose listener failures are logged and
|
|
10
|
+
* contained — a throwing observer cannot fail the append that produced it.
|
|
11
|
+
* - It reacts to `turn/end`, the moment the Turn is already committed and the
|
|
12
|
+
* conversation is no longer mid-flight.
|
|
13
|
+
* - It performs NO I/O inside that dispatch: the record is built from scalars
|
|
14
|
+
* the collector already holds and pushed onto a queue that a `setImmediate`
|
|
15
|
+
* drain appends later.
|
|
16
|
+
* - Every entry point is wrapped, and the plugin exports no `Config` schema, so
|
|
17
|
+
* it also has no runtime dependency on any `@deepseek-ai/*` package: a broken
|
|
18
|
+
* ledger degrades to a health counter in the dashboard, never to a failed
|
|
19
|
+
* Turn.
|
|
20
|
+
*
|
|
21
|
+
* @module dsh-token-usage-ledger
|
|
22
|
+
*/
|
|
23
|
+
import { buildSummary } from './host/aggregate.js';
|
|
24
|
+
import { createRouteHandler } from './host/api.js';
|
|
25
|
+
import { backfillLedger } from './host/backfill.js';
|
|
26
|
+
import { TurnUsageCollector } from './host/collector.js';
|
|
27
|
+
import { createBackup, parseBackup, readLedgerKeys, selectNewRecords, } from './host/ledger-io.js';
|
|
28
|
+
import { OperationError } from './host/operation-error.js';
|
|
29
|
+
import { resolveDshHome } from './host/paths.js';
|
|
30
|
+
import { buildPricingRule, PRICING_MODULES, pricingModuleById, provenanceOf, } from './host/pricing.js';
|
|
31
|
+
import { buildRecord } from './host/records.js';
|
|
32
|
+
import { removeRuntimeMarker, writeRuntimeMarker } from './host/runtime-marker.js';
|
|
33
|
+
import { LEDGER_DIR, UsageStore } from './host/store.js';
|
|
34
|
+
import { resolveWorkspaceTitles } from './host/workspace-titles.js';
|
|
35
|
+
/** Plugin id; matches the `id` used by this package's Cordis patch row. */
|
|
36
|
+
export const name = 'token-usage';
|
|
37
|
+
/**
|
|
38
|
+
* Plugin version, kept in sync with `package.json` by
|
|
39
|
+
* `tests/manifest.test.mjs`.
|
|
40
|
+
*/
|
|
41
|
+
export const PLUGIN_VERSION = '0.0.36';
|
|
42
|
+
/** Default route prefix for the browser-facing JSON endpoint. */
|
|
43
|
+
const DEFAULT_API_PATH = '/dsh-token-usage';
|
|
44
|
+
/**
|
|
45
|
+
* Coerce one unknown config value to a finite number inside bounds.
|
|
46
|
+
* @param value - raw value.
|
|
47
|
+
* @param fallback - value to use when the input is unusable.
|
|
48
|
+
* @param min - inclusive lower bound.
|
|
49
|
+
* @param max - inclusive upper bound.
|
|
50
|
+
* @returns the accepted number.
|
|
51
|
+
*/
|
|
52
|
+
function numberOr(value, fallback, min, max) {
|
|
53
|
+
if (typeof value !== 'number' || !Number.isFinite(value))
|
|
54
|
+
return fallback;
|
|
55
|
+
return Math.min(max, Math.max(min, value));
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Coerce one unknown config value to a non-empty string.
|
|
59
|
+
* @param value - raw value.
|
|
60
|
+
* @param fallback - value to use when the input is unusable.
|
|
61
|
+
* @returns the accepted string.
|
|
62
|
+
*/
|
|
63
|
+
function stringOr(value, fallback) {
|
|
64
|
+
if (typeof value !== 'string')
|
|
65
|
+
return fallback;
|
|
66
|
+
const trimmed = value.trim();
|
|
67
|
+
return trimmed.length === 0 ? fallback : trimmed;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Read a peak-price override map, discarding malformed rows.
|
|
71
|
+
* @param value - raw config value.
|
|
72
|
+
* @returns accepted overrides, possibly empty.
|
|
73
|
+
*/
|
|
74
|
+
function priceOverrides(value) {
|
|
75
|
+
const result = {};
|
|
76
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value))
|
|
77
|
+
return result;
|
|
78
|
+
for (const [model, prices] of Object.entries(value)) {
|
|
79
|
+
if (typeof prices !== 'object' || prices === null)
|
|
80
|
+
continue;
|
|
81
|
+
const row = prices;
|
|
82
|
+
const cacheHit = row['cacheHit'];
|
|
83
|
+
const cacheMiss = row['cacheMiss'];
|
|
84
|
+
const output = row['output'];
|
|
85
|
+
if (typeof cacheHit !== 'number' ||
|
|
86
|
+
typeof cacheMiss !== 'number' ||
|
|
87
|
+
typeof output !== 'number' ||
|
|
88
|
+
!Number.isFinite(cacheHit) ||
|
|
89
|
+
!Number.isFinite(cacheMiss) ||
|
|
90
|
+
!Number.isFinite(output) ||
|
|
91
|
+
cacheHit < 0 ||
|
|
92
|
+
cacheMiss < 0 ||
|
|
93
|
+
output < 0) {
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
result[model] = { cacheHit, cacheMiss, output };
|
|
97
|
+
}
|
|
98
|
+
return result;
|
|
99
|
+
}
|
|
100
|
+
/** Path prefixes the harness itself owns; a plugin route must not claim them. */
|
|
101
|
+
const RESERVED_PATH_PREFIXES = ['/api', '/plugins'];
|
|
102
|
+
/**
|
|
103
|
+
* Accept a route prefix only when the harness can actually serve it.
|
|
104
|
+
*
|
|
105
|
+
* `ctx.webServer.register` treats a path as a contract, so a bad one fails
|
|
106
|
+
* silently at request time rather than at load: `'api'` (no leading slash) is
|
|
107
|
+
* unreachable, and `/api` collides with the gateway's own seat, whose
|
|
108
|
+
* registration would then throw. Falling back to the default with a warning
|
|
109
|
+
* beats both.
|
|
110
|
+
*
|
|
111
|
+
* @param candidate - configured prefix.
|
|
112
|
+
* @param warn - sink for the rejection message.
|
|
113
|
+
* @returns a usable prefix.
|
|
114
|
+
*/
|
|
115
|
+
function normalizeApiPath(candidate, warn) {
|
|
116
|
+
const trimmed = candidate.endsWith('/') ? candidate.replace(/\/+$/, '') : candidate;
|
|
117
|
+
if (trimmed.length === 0 || !trimmed.startsWith('/')) {
|
|
118
|
+
warn(`apiPath ${JSON.stringify(candidate)} must be an absolute path; using ${DEFAULT_API_PATH}`);
|
|
119
|
+
return DEFAULT_API_PATH;
|
|
120
|
+
}
|
|
121
|
+
for (const reserved of RESERVED_PATH_PREFIXES) {
|
|
122
|
+
if (trimmed === reserved || trimmed.startsWith(`${reserved}/`)) {
|
|
123
|
+
warn(`apiPath ${JSON.stringify(candidate)} is reserved by the harness; using ${DEFAULT_API_PATH}`);
|
|
124
|
+
return DEFAULT_API_PATH;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return trimmed;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Normalize a raw Cordis row config into usable settings.
|
|
131
|
+
*
|
|
132
|
+
* Never throws: an unusable value falls back to its default so a typo in
|
|
133
|
+
* `cordis.patch.yml` cannot stop the plugin from loading, let alone the
|
|
134
|
+
* conversation from running.
|
|
135
|
+
*
|
|
136
|
+
* @param raw - config object supplied by the loader, possibly undefined or malformed.
|
|
137
|
+
* @returns complete settings.
|
|
138
|
+
*/
|
|
139
|
+
export function normalizeSettings(raw) {
|
|
140
|
+
const source = typeof raw === 'object' && raw !== null && !Array.isArray(raw)
|
|
141
|
+
? raw
|
|
142
|
+
: {};
|
|
143
|
+
const currency = source['currency'] === 'USD' ? 'USD' : 'CNY';
|
|
144
|
+
const hosts = source['extraAllowedHosts'];
|
|
145
|
+
const apiPath = stringOr(source['apiPath'], DEFAULT_API_PATH);
|
|
146
|
+
return {
|
|
147
|
+
dataDir: typeof source['dataDir'] === 'string' && source['dataDir'].trim() !== ''
|
|
148
|
+
? source['dataDir'].trim()
|
|
149
|
+
: undefined,
|
|
150
|
+
pricingModule: typeof source['pricingModule'] === 'string' ? source['pricingModule'].trim() : '',
|
|
151
|
+
currency,
|
|
152
|
+
offPeakRatio: numberOr(source['offPeakRatio'], 0.5, 0, 1),
|
|
153
|
+
peakOffsetMinutes: numberOr(source['peakOffsetMinutes'], 480, -720, 840),
|
|
154
|
+
fallbackModel: stringOr(source['fallbackModel'], 'deepseek-flash'),
|
|
155
|
+
models: priceOverrides(source['models']),
|
|
156
|
+
apiPath: normalizeApiPath(apiPath, () => { }),
|
|
157
|
+
extraAllowedHosts: Array.isArray(hosts)
|
|
158
|
+
? hosts.filter((host) => typeof host === 'string').map((host) => host.trim())
|
|
159
|
+
: [],
|
|
160
|
+
allowAnyHost: source['allowAnyHost'] === true,
|
|
161
|
+
maxPendingWrites: numberOr(source['maxPendingWrites'], 4096, 1, 1_000_000),
|
|
162
|
+
debug: source['debug'] === true,
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Plugin body.
|
|
167
|
+
*
|
|
168
|
+
* @param ctx - this plugin row's Cordis context; every side effect hangs off it.
|
|
169
|
+
* @param rawConfig - the row's `config` block, unvalidated by design.
|
|
170
|
+
*/
|
|
171
|
+
export function apply(ctx, rawConfig) {
|
|
172
|
+
const settings = normalizeSettings(rawConfig);
|
|
173
|
+
const prefix = `[${name}]`;
|
|
174
|
+
/**
|
|
175
|
+
* Emit one diagnostic line. Warnings are always emitted (they are the
|
|
176
|
+
* plugin's only failure channel); chatter is gated behind `debug`.
|
|
177
|
+
* @param message - text to log.
|
|
178
|
+
* @param always - whether to emit regardless of `debug`.
|
|
179
|
+
*/
|
|
180
|
+
const log = (message, always = false) => {
|
|
181
|
+
if (!always && !settings.debug)
|
|
182
|
+
return;
|
|
183
|
+
try {
|
|
184
|
+
console.warn(`${prefix} ${message}`);
|
|
185
|
+
}
|
|
186
|
+
catch {
|
|
187
|
+
// A throwing console must not escalate.
|
|
188
|
+
}
|
|
189
|
+
};
|
|
190
|
+
const home = resolveDshHome();
|
|
191
|
+
const dir = settings.dataDir ?? `${home}/${LEDGER_DIR}`;
|
|
192
|
+
const store = new UsageStore({
|
|
193
|
+
dir,
|
|
194
|
+
maxPending: settings.maxPendingWrites,
|
|
195
|
+
warn: (message) => {
|
|
196
|
+
log(message, true);
|
|
197
|
+
},
|
|
198
|
+
});
|
|
199
|
+
// A price era is selected by id; an unknown id falls back to the default and
|
|
200
|
+
// says so, because silently pricing with the wrong era would be worse than a
|
|
201
|
+
// warning. Older eras stay registered so a deployment can switch back.
|
|
202
|
+
const requested = settings.pricingModule;
|
|
203
|
+
const selected = requested === '' ? undefined : pricingModuleById(requested);
|
|
204
|
+
if (requested !== '' && selected === undefined) {
|
|
205
|
+
log(`unknown pricingModule ${JSON.stringify(requested)}; falling back to ${PRICING_MODULES[0]?.id ?? '?'}` +
|
|
206
|
+
` (available: ${PRICING_MODULES.map((module) => module.id).join(', ')})`, true);
|
|
207
|
+
}
|
|
208
|
+
const rule = buildPricingRule({
|
|
209
|
+
...(selected === undefined ? {} : { module: selected }),
|
|
210
|
+
currency: settings.currency,
|
|
211
|
+
overrides: settings.models,
|
|
212
|
+
offPeakRatio: settings.offPeakRatio,
|
|
213
|
+
peakOffsetMinutes: settings.peakOffsetMinutes,
|
|
214
|
+
fallbackModel: settings.fallbackModel,
|
|
215
|
+
});
|
|
216
|
+
const pricingProvenance = provenanceOf(rule);
|
|
217
|
+
/** One collector per Session with an observed open Turn. */
|
|
218
|
+
const collectors = new Map();
|
|
219
|
+
/** Turns the collector saw but could not prove, and therefore did not record. */
|
|
220
|
+
let skippedTurns = 0;
|
|
221
|
+
// The startup marker answers "is the RUNNING service on the new build?" from
|
|
222
|
+
// disk, so verification needs neither the launch token nor a browser. Written
|
|
223
|
+
// here (plugin load) and removed on unload: a leftover file cannot be mistaken
|
|
224
|
+
// for a live instance because the reader also checks the pid.
|
|
225
|
+
ctx.effect(() => {
|
|
226
|
+
writeRuntimeMarker(dir, {
|
|
227
|
+
pluginVersion: PLUGIN_VERSION,
|
|
228
|
+
pid: process.pid,
|
|
229
|
+
startedAt: new Date().toISOString(),
|
|
230
|
+
dataDir: dir,
|
|
231
|
+
apiPath: settings.apiPath,
|
|
232
|
+
pricing: { module: rule.module.id, currency: rule.currency },
|
|
233
|
+
}, (message) => {
|
|
234
|
+
log(message, true);
|
|
235
|
+
});
|
|
236
|
+
return () => {
|
|
237
|
+
removeRuntimeMarker(dir);
|
|
238
|
+
};
|
|
239
|
+
}, `${name}: runtime marker`);
|
|
240
|
+
ctx.effect(() => {
|
|
241
|
+
const disposeEvent = ctx.on('session/event', (session, event) => {
|
|
242
|
+
// This whole body sits inside the Session store's contained observer
|
|
243
|
+
// dispatch AND its own try/catch: two independent reasons a failure
|
|
244
|
+
// here can never reach the conversation.
|
|
245
|
+
try {
|
|
246
|
+
observeTurn(session, event);
|
|
247
|
+
}
|
|
248
|
+
catch (error) {
|
|
249
|
+
skippedTurns += 1;
|
|
250
|
+
log(`dropped a turn while recording: ${error instanceof Error ? error.message : String(error)}`, true);
|
|
251
|
+
}
|
|
252
|
+
});
|
|
253
|
+
const disposeSession = ctx.on('session/disposed', (session) => {
|
|
254
|
+
// Wrapped for the same reason the append feed is: the harness contains a
|
|
255
|
+
// throwing listener, but a plugin that promises containment should not
|
|
256
|
+
// rely on it, and this path was the one exception.
|
|
257
|
+
try {
|
|
258
|
+
collectors.delete(String(session.id));
|
|
259
|
+
}
|
|
260
|
+
catch (error) {
|
|
261
|
+
log(`could not release a disposed session: ${error instanceof Error ? error.message : String(error)}`, true);
|
|
262
|
+
}
|
|
263
|
+
});
|
|
264
|
+
return () => {
|
|
265
|
+
disposeEvent();
|
|
266
|
+
disposeSession();
|
|
267
|
+
collectors.clear();
|
|
268
|
+
// Best-effort: flush whatever is queued so a clean unload is not lossy.
|
|
269
|
+
void store.flush();
|
|
270
|
+
};
|
|
271
|
+
}, `${name}: ledger observer`);
|
|
272
|
+
/**
|
|
273
|
+
* Feed one event into the right Session's collector and persist a record when
|
|
274
|
+
* a Turn closes.
|
|
275
|
+
* @param session - the Session whose log grew.
|
|
276
|
+
* @param event - the committed event.
|
|
277
|
+
*/
|
|
278
|
+
function observeTurn(session, event) {
|
|
279
|
+
const sessionId = String(session.id);
|
|
280
|
+
let collector = collectors.get(sessionId);
|
|
281
|
+
if (collector === undefined) {
|
|
282
|
+
// Begin only at a Turn boundary this process actually observed, so a
|
|
283
|
+
// session adopted mid-turn contributes nothing rather than a partial line.
|
|
284
|
+
if (event.type !== 'turn/start')
|
|
285
|
+
return;
|
|
286
|
+
collector = new TurnUsageCollector();
|
|
287
|
+
collectors.set(sessionId, collector);
|
|
288
|
+
}
|
|
289
|
+
const result = collector.push(event);
|
|
290
|
+
if (result.kind !== 'closed')
|
|
291
|
+
return;
|
|
292
|
+
collectors.delete(sessionId);
|
|
293
|
+
if (result.outcome === undefined) {
|
|
294
|
+
skippedTurns += 1;
|
|
295
|
+
log(`turn could not be proven from its durable events; not recorded`);
|
|
296
|
+
return;
|
|
297
|
+
}
|
|
298
|
+
store.enqueue(buildRecord(result.outcome, recordContextOf(session), rule));
|
|
299
|
+
}
|
|
300
|
+
// ---- Data backup / import / backfill operations.
|
|
301
|
+
//
|
|
302
|
+
// These are the only paths that write the ledger outside the live collector,
|
|
303
|
+
// so they share one lock: an import and a backfill cannot interleave, and an
|
|
304
|
+
// export cannot read a half-appended batch. The lock is process-local; the
|
|
305
|
+
// HTTP layer also disables the buttons while a request is in flight.
|
|
306
|
+
let dataOperation = null;
|
|
307
|
+
/**
|
|
308
|
+
* Run one data operation under the shared lock.
|
|
309
|
+
* @param operation - operation name for diagnostics.
|
|
310
|
+
* @param run - operation body.
|
|
311
|
+
* @returns the operation result.
|
|
312
|
+
*/
|
|
313
|
+
async function withDataLock(operation, run) {
|
|
314
|
+
if (dataOperation !== null) {
|
|
315
|
+
throw new OperationError(409, 'busy', 'another data operation is already running');
|
|
316
|
+
}
|
|
317
|
+
dataOperation = operation;
|
|
318
|
+
try {
|
|
319
|
+
return await run();
|
|
320
|
+
}
|
|
321
|
+
finally {
|
|
322
|
+
dataOperation = null;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
const exportBackup = async () => await withDataLock('export', async () => {
|
|
326
|
+
await store.flush();
|
|
327
|
+
return await createBackup(store.filePath, PLUGIN_VERSION);
|
|
328
|
+
});
|
|
329
|
+
const importBackup = async (body) => await withDataLock('import', async () => {
|
|
330
|
+
// Flush first: the live queue may hold turns that are not in the file yet;
|
|
331
|
+
// they must participate in the duplicate check.
|
|
332
|
+
await store.flush();
|
|
333
|
+
const parsed = parseBackup(body);
|
|
334
|
+
if (parsed.invalid > 0 || parsed.unsupported > 0) {
|
|
335
|
+
throw new OperationError(400, 'import-invalid', `backup contains ${String(parsed.invalid)} invalid and ${String(parsed.unsupported)} unsupported records; nothing was imported`);
|
|
336
|
+
}
|
|
337
|
+
const existing = await readLedgerKeys(store.filePath);
|
|
338
|
+
const selected = selectNewRecords(parsed.records, existing);
|
|
339
|
+
const appended = await store.appendRecords(selected.records);
|
|
340
|
+
if (appended.written !== selected.records.length) {
|
|
341
|
+
throw new OperationError(500, 'write-failed', 'could not append imported records');
|
|
342
|
+
}
|
|
343
|
+
return {
|
|
344
|
+
added: appended.written,
|
|
345
|
+
duplicates: selected.duplicates,
|
|
346
|
+
invalid: 0,
|
|
347
|
+
total: parsed.total,
|
|
348
|
+
unsupported: 0,
|
|
349
|
+
};
|
|
350
|
+
});
|
|
351
|
+
const runBackfill = async (dryRun) => await withDataLock('backfill', async () => {
|
|
352
|
+
await store.flush();
|
|
353
|
+
const outcome = await backfillLedger({
|
|
354
|
+
home,
|
|
355
|
+
ledgerPath: store.filePath,
|
|
356
|
+
rule,
|
|
357
|
+
onWarning: (message) => {
|
|
358
|
+
log(message, true);
|
|
359
|
+
},
|
|
360
|
+
});
|
|
361
|
+
let written = 0;
|
|
362
|
+
if (!dryRun && outcome.records.length > 0) {
|
|
363
|
+
const appended = await store.appendRecords(outcome.records);
|
|
364
|
+
if (appended.written !== outcome.records.length) {
|
|
365
|
+
throw new OperationError(500, 'write-failed', 'could not append backfilled records');
|
|
366
|
+
}
|
|
367
|
+
written = appended.written;
|
|
368
|
+
}
|
|
369
|
+
return { dryRun, written, report: outcome.report };
|
|
370
|
+
});
|
|
371
|
+
// The dashboard route is registered through `ctx.inject` rather than read
|
|
372
|
+
// eagerly with `ctx.get`: the web server is contributed by another row, and
|
|
373
|
+
// the composition order decides whether it exists yet when this row's `apply`
|
|
374
|
+
// runs. `inject` registers the callback for whenever the service is present
|
|
375
|
+
// and disposes it if it goes away — which is also why the ledger keeps
|
|
376
|
+
// recording on a headless profile where `webServer` never appears.
|
|
377
|
+
ctx.inject(['webServer'], (scope) => {
|
|
378
|
+
const scoped = scope;
|
|
379
|
+
const webServer = scoped.webServer;
|
|
380
|
+
// Prefer the harness's own browser-trust + authentication fence whenever the
|
|
381
|
+
// composition provides one: it knows the deployment's trusted hosts AND can
|
|
382
|
+
// verify the signed browser cookie, which this plugin cannot. It is resolved
|
|
383
|
+
// per request because the connection service is another row's contribution
|
|
384
|
+
// and its presence at registration time is a composition-order accident.
|
|
385
|
+
void scoped;
|
|
386
|
+
let reportedFenceMode = false;
|
|
387
|
+
const handler = createRouteHandler({
|
|
388
|
+
prefix: settings.apiPath,
|
|
389
|
+
access: {
|
|
390
|
+
extraAllowedHosts: settings.extraAllowedHosts,
|
|
391
|
+
allowAnyHost: settings.allowAnyHost,
|
|
392
|
+
fenceFor: (request) => {
|
|
393
|
+
const fence = resolveFence(ctx, request.headers);
|
|
394
|
+
if (!reportedFenceMode) {
|
|
395
|
+
reportedFenceMode = true;
|
|
396
|
+
log(fence === undefined
|
|
397
|
+
? `serving ${settings.apiPath} with the plugin's own host checks (no connection service in this composition)`
|
|
398
|
+
: `serving ${settings.apiPath} behind the harness browser-trust fence`, true);
|
|
399
|
+
}
|
|
400
|
+
return fence;
|
|
401
|
+
},
|
|
402
|
+
},
|
|
403
|
+
warn: (message) => {
|
|
404
|
+
log(message, true);
|
|
405
|
+
},
|
|
406
|
+
summarize: async (query) => {
|
|
407
|
+
const snapshot = await store.load();
|
|
408
|
+
// A Workspace rename changes only its title, never its directory path,
|
|
409
|
+
// so resolve the current titles per request instead of trusting the
|
|
410
|
+
// basename frozen into each ledger line. Missing registry/service
|
|
411
|
+
// degrades to the stored labels inside `resolveWorkspaceTitles`.
|
|
412
|
+
const workspaceTitles = await resolveWorkspaceTitles(ctx, snapshot.records);
|
|
413
|
+
return buildSummary({
|
|
414
|
+
records: snapshot.records,
|
|
415
|
+
workspace: query.workspace,
|
|
416
|
+
model: query.model,
|
|
417
|
+
provider: query.provider,
|
|
418
|
+
days: query.days,
|
|
419
|
+
now: Date.now(),
|
|
420
|
+
currency: rule.currency,
|
|
421
|
+
pluginVersion: PLUGIN_VERSION,
|
|
422
|
+
pricing: pricingProvenance,
|
|
423
|
+
health: store.stats({ skippedTurns }),
|
|
424
|
+
workspaceTitleOf: (workspace) => workspaceTitles.get(workspace),
|
|
425
|
+
});
|
|
426
|
+
},
|
|
427
|
+
exportBackup,
|
|
428
|
+
importBackup,
|
|
429
|
+
backfill: runBackfill,
|
|
430
|
+
});
|
|
431
|
+
scope.effect(() => {
|
|
432
|
+
let dispose;
|
|
433
|
+
try {
|
|
434
|
+
dispose = webServer.register({
|
|
435
|
+
kind: 'prefix',
|
|
436
|
+
path: settings.apiPath,
|
|
437
|
+
handler,
|
|
438
|
+
});
|
|
439
|
+
}
|
|
440
|
+
catch (error) {
|
|
441
|
+
// A taken prefix is a composition conflict; report it and keep recording.
|
|
442
|
+
log(`could not register ${settings.apiPath}: ${error instanceof Error ? error.message : String(error)}`, true);
|
|
443
|
+
return () => { };
|
|
444
|
+
}
|
|
445
|
+
return () => {
|
|
446
|
+
try {
|
|
447
|
+
dispose?.();
|
|
448
|
+
}
|
|
449
|
+
catch {
|
|
450
|
+
// Disposal is already the teardown path; nothing further to do.
|
|
451
|
+
}
|
|
452
|
+
};
|
|
453
|
+
}, `${name}: summary route`);
|
|
454
|
+
log(`serving the dashboard summary at ${settings.apiPath}`, true);
|
|
455
|
+
});
|
|
456
|
+
log(`recording to ${store.filePath}; pricing ${rule.currency} @ ${pricingProvenance.version}` +
|
|
457
|
+
` (module ${rule.module.id}; earliest row ${earliestRow(rule.module)})`, true);
|
|
458
|
+
}
|
|
459
|
+
/**
|
|
460
|
+
* Resolve the harness's request fence, if this composition has one.
|
|
461
|
+
*
|
|
462
|
+
* Kept as a small shim so `host/api.ts` stays free of any harness type and can
|
|
463
|
+
* be unit-tested without one. Read through `ctx.get` at REQUEST time so the
|
|
464
|
+
* route works whatever order the rows load in.
|
|
465
|
+
*
|
|
466
|
+
* @param ctx - the plugin's context.
|
|
467
|
+
* @param headers - headers of the request being authorized.
|
|
468
|
+
* @returns the fence callable, or undefined when no fence is available.
|
|
469
|
+
*/
|
|
470
|
+
function resolveFence(ctx, headers) {
|
|
471
|
+
const connection = ctx.get('connection');
|
|
472
|
+
if (connection === undefined || typeof connection.requestRejection !== 'function') {
|
|
473
|
+
return undefined;
|
|
474
|
+
}
|
|
475
|
+
return () => connection.requestRejection({
|
|
476
|
+
headers: (headers ?? {}),
|
|
477
|
+
});
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Project a live Session's immutable header into the record context.
|
|
481
|
+
* @param session - Session that produced the Turn.
|
|
482
|
+
* @returns the identity fields stored on the record.
|
|
483
|
+
*/
|
|
484
|
+
function recordContextOf(session) {
|
|
485
|
+
const header = session.header;
|
|
486
|
+
return {
|
|
487
|
+
sessionId: String(session.id),
|
|
488
|
+
workspace: header.cwd ?? '',
|
|
489
|
+
agentPreset: header.agentPreset ?? '',
|
|
490
|
+
origin: header.origin ?? '',
|
|
491
|
+
delegationDepth: header.delegationDepth ?? 0,
|
|
492
|
+
parentSession: header.parentSession === undefined ? '' : String(header.parentSession),
|
|
493
|
+
};
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* Earliest dated row of a price era, for the startup log.
|
|
497
|
+
* @param module - price era.
|
|
498
|
+
* @returns the earliest `effectiveFrom`, or `'?'` when it has no rows.
|
|
499
|
+
*/
|
|
500
|
+
function earliestRow(module) {
|
|
501
|
+
let earliest = '';
|
|
502
|
+
for (const byModel of Object.values(module.prices)) {
|
|
503
|
+
for (const rows of Object.values(byModel)) {
|
|
504
|
+
for (const row of rows) {
|
|
505
|
+
if (earliest === '' || row.effectiveFrom < earliest)
|
|
506
|
+
earliest = row.effectiveFrom;
|
|
507
|
+
}
|
|
508
|
+
}
|
|
509
|
+
}
|
|
510
|
+
return earliest === '' ? '?' : earliest;
|
|
511
|
+
}
|
|
512
|
+
//# sourceMappingURL=index.js.map
|