dsh-token-usage-ledger 0.0.0-stage → 0.0.37

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.
Files changed (48) hide show
  1. package/CHANGELOG.md +1081 -0
  2. package/LICENSE +21 -0
  3. package/README.md +247 -2
  4. package/cordis.patch.yml +30 -0
  5. package/docs/token-usage-image01.png +0 -0
  6. package/docs/token-usage-image02.png +0 -0
  7. package/lib/client.js +4469 -0
  8. package/lib/host/aggregate.d.ts +132 -0
  9. package/lib/host/aggregate.js +840 -0
  10. package/lib/host/api.d.ts +118 -0
  11. package/lib/host/api.js +346 -0
  12. package/lib/host/backfill.d.ts +54 -0
  13. package/lib/host/backfill.js +265 -0
  14. package/lib/host/collector.d.ts +139 -0
  15. package/lib/host/collector.js +441 -0
  16. package/lib/host/ledger-io.d.ts +125 -0
  17. package/lib/host/ledger-io.js +211 -0
  18. package/lib/host/operation-error.d.ts +22 -0
  19. package/lib/host/operation-error.js +28 -0
  20. package/lib/host/paths.d.ts +35 -0
  21. package/lib/host/paths.js +63 -0
  22. package/lib/host/pricing-module.d.ts +112 -0
  23. package/lib/host/pricing-module.js +63 -0
  24. package/lib/host/pricing-modules/deepseek-2026-09-10.d.ts +31 -0
  25. package/lib/host/pricing-modules/deepseek-2026-09-10.js +67 -0
  26. package/lib/host/pricing-modules/index.d.ts +27 -0
  27. package/lib/host/pricing-modules/index.js +30 -0
  28. package/lib/host/pricing.d.ts +192 -0
  29. package/lib/host/pricing.js +287 -0
  30. package/lib/host/records.d.ts +47 -0
  31. package/lib/host/records.js +116 -0
  32. package/lib/host/runtime-marker.d.ts +67 -0
  33. package/lib/host/runtime-marker.js +71 -0
  34. package/lib/host/schema.d.ts +77 -0
  35. package/lib/host/schema.js +158 -0
  36. package/lib/host/store.d.ts +171 -0
  37. package/lib/host/store.js +337 -0
  38. package/lib/host/workspace-titles.d.ts +38 -0
  39. package/lib/host/workspace-titles.js +136 -0
  40. package/lib/host/zstd.d.ts +41 -0
  41. package/lib/host/zstd.js +134 -0
  42. package/lib/index.d.ts +82 -0
  43. package/lib/index.js +512 -0
  44. package/lib/shared/format.d.ts +415 -0
  45. package/lib/shared/format.js +714 -0
  46. package/lib/shared/protocol.d.ts +646 -0
  47. package/lib/shared/protocol.js +129 -0
  48. package/package.json +87 -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.37";
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.37';
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