dsh-plugin-usage 0.2.0 → 0.3.0

package/lib/host/fold.js

@@ -1,60 +1,167 @@
 /**
- * Fold session events into usage records.
+ * Fold durable session events into usage records.
  *
- * foldNew is called by scan.js for both live and persisted sessions.
+ * This mirrors the official `tokenUsage` session projection
+ * (@deepseek-ai/dsh-token-meter) so a third-party dashboard and the built-in
+ * stats agree on what one session consumed:
  *
- * P0-2: dedup ownership lives here. Records are keyed by
- * state.dedup (sessionId + turn + step); a later sample for the same
- * (turn, step) REPLACES the previous one in place instead of appending,
- * calling state.index.remove() for the dropped record and state.index.add()
- * for the replacement. Records without turn/step (legacy logs) are never
- * deduped — they always append.
+ *  - A **billed settlement** is `assistant/message` or `assistant/attempt`.
+ *    `assistant/message` carries `data.usage`; a retried/failed attempt has no
+ *    usage field but can still have reported usage on its exact stream, so the
+ *    last raw `usage` chunk of `data.stream` is used when the field is absent.
+ *  - `llm/retry-started` closes the replacement slot for that (turn, step):
+ *    the retried attempt is a NEW billable attempt and must add, not replace.
+ *  - Otherwise a later sample for the same (turn, step) replaces the previous
+ *    one in place (index remove + add), because a settlement re-reports the
+ *    cumulative usage of its step.
+ *  - `request/context` and `request/header` provide the route (provider/model)
+ *    for settlements that carry no `message.source`.
+ *
+ * Records without turn/step (legacy logs) are never deduped — they always
+ * append.
+ */
+/**
+ * Last raw `usage` chunk of one durable assistant stream.
+ *
+ * @param {unknown} stream - `AssistantStreamRecord[]` (packed records included).
+ * @returns {object | undefined} the reported usage, when the stream has one.
+ */
+export function streamUsage(stream) {
+    if (!Array.isArray(stream))
+        return undefined;
+    for (let index = stream.length - 1; index >= 0; index -= 1) {
+        const record = stream[index];
+        if (record && record.type === 'chunk' && record.chunk && record.chunk.type === 'usage') {
+            return record.chunk.usage;
+        }
+    }
+    return undefined;
+}
+/**
+ * Usage reported by one durable assistant settlement.
+ *
+ * @param {{ type?: string, data?: any }} event - session event.
+ * @returns {object | undefined} reported usage, when the settlement billed one.
+ */
+export function usageOf(event) {
+    const data = event && event.data;
+    if (event.type === 'assistant/message' && data && data.usage !== undefined)
+        return data.usage;
+    if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt')
+        return undefined;
+    return streamUsage(data && data.stream);
+}
+/** Route carried by a request event, when present. */
+function routeOf(event) {
+    const data = event.data || {};
+    if (event.type === 'request/context') {
+        if (typeof data.provider === 'string' && typeof data.model === 'string') {
+            return { provider: data.provider, model: data.model };
+        }
+        return undefined;
+    }
+    if (event.type === 'request/header') {
+        const config = data.header && data.header.config;
+        if (config && typeof config.provider === 'string' && typeof config.model === 'string') {
+            return { provider: config.provider, model: config.model };
+        }
+    }
+    return undefined;
+}
+/**
+ * Fold one durable event into the usage records.
+ *
+ * @param {object} state - runtime state capsule (see state.js).
+ * @param {string} sessionId - owning session.
+ * @param {{ type?: string, seq?: number, time?: number, data?: any }} e - session event.
+ * @returns {object | null} the affected record, or null when the event billed nothing.
  */
 export function foldEvent(state, sessionId, e) {
-    if (!e || e.type !== 'assistant/message' || !e.data || !e.data.usage)
+    if (!e || typeof e !== 'object')
+        return null;
+    // Route tracking: every settlement of a turn is priced/attributed under the
+    // route its request ran on.
+    const route = routeOf(e);
+    if (route !== undefined) {
+        state.route.set(sessionId, route);
+        return null;
+    }
+    // Retry boundary: the retried attempt is a new billable attempt.
+    if (e.type === 'llm/retry-started') {
+        const data = e.data || {};
+        const last = state.lastSample.get(sessionId);
+        if (last && last.turn === data.turn && last.step === data.step) {
+            state.lastSample.delete(sessionId);
+        }
+        return null;
+    }
+    if (e.type !== 'assistant/message' && e.type !== 'assistant/attempt')
         return null;
-    const source = (e.data.message && e.data.message.source) || {};
-    const u = e.data.usage;
+    const usage = usageOf(e);
+    if (usage === undefined || usage === null || typeof usage !== 'object')
+        return null;
+    const data = e.data || {};
+    const source = (data.message && data.message.source) || state.route.get(sessionId) || {};
+    const u = usage;
+    const inputTokens = u.inputTokens || 0;
+    const outputTokens = u.outputTokens || 0;
+    const cacheReadTokens = u.cacheReadTokens || 0;
+    const cacheWriteTokens = u.cacheWriteTokens || 0;
     const rec = {
         time: e.time,
         session: sessionId,
         provider: source.provider || '',
         model: source.model || '',
-        turn: e.data.turn,
-        step: e.data.step,
-        inputTokens: u.inputTokens || 0,
-        outputTokens: u.outputTokens || 0,
-        cacheReadTokens: u.cacheReadTokens || 0,
-        cacheWriteTokens: u.cacheWriteTokens || 0,
+        turn: data.turn,
+        step: data.step,
+        attempt: e.type === 'assistant/attempt',
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
         reasoningTokens: u.reasoningTokens || 0,
-        totalTokens: (u.inputTokens || 0) + (u.outputTokens || 0) + (u.cacheReadTokens || 0) + (u.cacheWriteTokens || 0),
+        // Prefer the provider's authoritative full-call total when reported.
+        totalTokens: typeof u.totalTokens === 'number'
+            ? u.totalTokens
+            : inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
     };
-    const key = sessionId + ':' + rec.turn + ':' + rec.step;
-    if (rec.turn !== undefined && rec.step !== undefined) {
-        const prevIndex = state.dedup.get(key);
-        if (prevIndex !== undefined) {
-            const prev = state.records[prevIndex];
-            if (state.index)
-                state.index.remove(prev);
-            Object.assign(prev, rec);
-            if (state.index)
-                state.index.add(prev);
-            return prev;
-        }
-        state.records.push(rec);
-        state.dedup.set(key, state.records.length - 1);
+    const previous = state.lastSample.get(sessionId);
+    if (previous !== undefined
+        && data.turn !== undefined && data.step !== undefined
+        && previous.turn === data.turn && previous.step === data.step) {
+        const prev = previous.record;
         if (state.index)
-            state.index.add(rec);
-        return rec;
+            state.index.remove(prev);
+        Object.assign(prev, rec);
+        if (state.index)
+            state.index.add(prev);
+        state.lastSample.set(sessionId, { turn: data.turn, step: data.step, record: prev });
+        return prev;
     }
     state.records.push(rec);
     if (state.index)
         state.index.add(rec);
+    if (data.turn !== undefined && data.step !== undefined) {
+        state.lastSample.set(sessionId, { turn: data.turn, step: data.step, record: rec });
+    }
+    else {
+        state.lastSample.delete(sessionId);
+    }
     return rec;
 }
-/** Fold events with seq > watermark for one session; returns new watermark. */
+/**
+ * Fold events with seq > watermark for one session; returns the new watermark.
+ *
+ * @param {object} state - runtime state capsule.
+ * @param {string} sessionId - owning session.
+ * @param {ReadonlyArray<object>} events - events in log order.
+ * @param {number} wm - current watermark (last folded seq).
+ * @returns {number} the new watermark.
+ */
 export function foldNew(state, sessionId, events, wm) {
     let max = wm;
+    if (!Array.isArray(events))
+        return max;
     for (const e of events) {
         if (e && typeof e.seq === 'number' && e.seq > wm) {
             foldEvent(state, sessionId, e);

package/lib/host/index.js

@@ -3,33 +3,51 @@
  *
  * Wires the submodules (fold / scan / query / settings / aggregate / rpc /
  * client-source) into the cordis plugin lifecycle. Strategy notes:
- *  - DSH already persists every loop model call's token usage durably in each
- *    session log as `assistant/message` events carrying `usage` (TokenUsage)
- *    and `message.source.{provider,model}`. We fold those events instead of
+ *  - DSH persists every loop model call's token usage in each session log as
+ *    an `assistant/message` (or `assistant/attempt`) settlement carrying
+ *    `usage`; this plugin folds those events with the same replacement /
+ *    retry semantics as the official `tokenUsage` projection instead of
  *    tapping `llm/stream` (unreachable from an agent-scoped dynamic plugin).
  *  - Live sessions are scanned from the in-memory store every poll tick;
  *    persisted sessions are backfilled at startup and re-scanned incrementally
- *    on a slower cadence (watermark per session).
+ *    (watermark + revision per session).
  *  - Aggregation, cost (user-configurable price table) and model list are
- *    served to the Client via the RPC bridge (rpc.js).
+ *    served through src/host/rpc.js.
+ *
+ * The price table is the plugin's own config: the exported `Config` schema is
+ * the official, durable form surface (`Plugins` settings tab -> profile
+ * patch), replacing the 0.1.x `settings.register`/`settings.yaml` path that
+ * does not exist in DSH 0.2.x.
  *
  * The same entry doubles as the cordis.yml host plugin module (exports name /
- * inject / apply) and as the `code.host` function body for a dynamic plugin.
+ * inject / Config / apply) and as the `code.host` function body for a dynamic
+ * plugin.
  */
-export const name = 'usage-host';
-export const inject = ['timer'];
-import { DEFAULT_PRICES, DEFAULT_CURRENCY, createPriceStore, initSettings } from './settings.js';
+import Schema from '@deepseek-ai/schemastery';
+import { DEFAULT_PRICES, DEFAULT_CURRENCY, createPriceStore, mergePrices } from './settings.js';
 import { createState } from './state.js';
 import { createUsageIndex } from './aggregate.js';
 import { scanLive, scanPersisted, runBackfill } from './scan.js';
 import { query } from './query.js';
 import { registerRPC } from './rpc.js';
 import { getClientSource } from './client-source.js';
+export const name = 'usage-host';
+export const inject = ['timer'];
+/** Durable price table + currency, materialized as the plugin's config form. */
+export const Config = Schema.object({
+    currency: Schema.string().default(DEFAULT_CURRENCY),
+    prices: Schema.dict(Schema.object({
+        inputPerM: Schema.number().default(0),
+        outputPerM: Schema.number().default(0),
+        cacheReadPerM: Schema.number().default(0),
+        cacheWritePerM: Schema.number().default(0),
+    })).default(DEFAULT_PRICES),
+});
 const LIVE_POLL_MS = 2000;
 const PERSISTED_POLL_MS = 30000;
-export function apply(ctx) {
-    const priceStore = createPriceStore(DEFAULT_PRICES, DEFAULT_CURRENCY);
-    initSettings(ctx, priceStore);
+export function apply(ctx, config) {
+    const resolved = config && typeof config === 'object' ? config : {};
+    const priceStore = createPriceStore(mergePrices(resolved.prices), resolved.currency || DEFAULT_CURRENCY);
     const state = createState(priceStore);
     state.index = createUsageIndex(state);
     const handlers = new Map();
@@ -39,6 +57,19 @@ export function apply(ctx) {
         store.setPrices(args && args.prices);
         if (args && typeof args.currency === 'string')
             store.setCurrency(args.currency);
+        // Secondary durability for hosts where the client cannot reach its config
+        // form: write the same values through the official SettingsForms API.
+        // The entry id is the bundle patch row id (`usage`).
+        try {
+            const settings = typeof ctx.get === 'function' ? ctx.get('settings') : undefined;
+            if (settings && typeof settings.update === 'function') {
+                settings.update('usage', { prices: Object.assign({}, store.prices), currency: store.currency })
+                    .catch(() => { });
+            }
+        }
+        catch {
+            // settings is optional; the in-memory store still answers this session.
+        }
         return store.snapshot();
     });
     handlers.set('client-source', () => getClientSource(ctx));
@@ -46,7 +77,7 @@ export function apply(ctx) {
     // Full history scan once at startup.
     runBackfill(ctx, state);
     // Live sessions every tick; persisted sessions on a slow cadence to keep
-    // per-session JSONL re-parsing cheap.
+    // per-session log reads cheap (unchanged revisions are skipped).
     ctx.interval(() => {
         scanLive(ctx, state);
     }, LIVE_POLL_MS);

package/lib/host/query.js

@@ -5,6 +5,7 @@
  * by-model table and model candidate list) are owned here.
  */
 import { dayKey, DAY_MS, bucketKeyFor, stepMs, alignFloor, stepDayKey, MAX_BUCKETS, } from './time.js';
+import { currencyOf } from './settings.js';
 function emptyBucket(key) {
     return {
         key,
@@ -52,7 +53,7 @@ export function query(state, args) {
     const dailyMap = new Map();
     const modelMap = new Map();
     const total = emptyBucket('total');
-    const seenModels = new Map(); // composite key -> {provider, model} (first composite wins)
+    const seenModels = new Map(); // composite key -> {key, provider, model} (first composite wins)
     let unpricedCalls = 0;
     // Range-anchored day-step grid: blocks start at the range's first day.
     const dayAnchor = Number.isFinite(from) ? alignFloor(from, 'day') : null;
@@ -60,14 +61,17 @@ export function query(state, args) {
     for (const r of state.index ? state.index.recordsInRange(from, to) : state.records) {
         if (r.time < from || r.time > to)
             continue;
+        // Candidate list first, selection filter second: the dropdown must offer
+        // every model that has data in the range, not only the ones already ticked
+        // (ticking one used to collapse the list to that single entry).
+        const modelKey = compositeModelKey(r);
+        if (!seenModels.has(modelKey))
+            seenModels.set(modelKey, { key: modelKey, provider: r.provider, model: r.model });
         if (!modelMatches(r))
             continue;
         const cost = state.prices.costOf(r);
         if (r.totalTokens > 0 && !state.prices.hasPrice(r))
             unpricedCalls += 1;
-        const modelKey = compositeModelKey(r);
-        if (!seenModels.has(modelKey))
-            seenModels.set(modelKey, { provider: r.provider, model: r.model });
         const dk = useStepGrid ? stepDayKey(r, dayAnchor, stepDays) : bucketKeyFor(r.time, granularity, stepDays);
         let db = dailyMap.get(dk);
         if (db === undefined) {
@@ -145,12 +149,28 @@ export function query(state, args) {
             heatmap.push(hmMap.get(k) || emptyBucket(k));
         }
     }
+    // Display currency: the price table is denominated in USD and stays as it is
+    // (it is shared, polled, and never mutated per request). Conversion happens
+    // here, once, at the output boundary — including the heatmap and the totals,
+    // so no two views of the same data disagree. Six decimals keep float tails
+    // out of the sums.
+    const money = currencyOf(args.currency, state.prices.currency);
+    const toDisplay = (v) => (money.perUsd === 1 ? v : Math.round(v * money.perUsd * 1e6) / 1e6);
+    for (const b of daily)
+        b.cost = toDisplay(b.cost);
+    for (const b of byModel)
+        b.cost = toDisplay(b.cost);
+    total.cost = toDisplay(total.cost);
+    if (heatmap !== null)
+        for (const b of heatmap)
+            b.cost = toDisplay(b.cost);
     return {
         daily,
         byModel,
         total,
         models,
         unpricedCalls,
+        currency: { code: money.code, symbol: money.symbol },
         ...heatmap === null ? {} : { heatmap },
         backfill: { status: state.backfill.status, total: state.backfill.total, done: state.backfill.done },
     };

package/lib/host/rpc.js

@@ -2,12 +2,109 @@
  * RPC registration.
  *
  * Dynamic-plugin runs expose `harness` directly; static (bundle) installs
- * expose the generic Connection RPC bridge (the browser half calls
- * connection.rpc.call('/usage', endpoint, args)). Support both from one file.
+ * expose the Connection service. Support both from one file, plus the
+ * official Typert gateway path (P0-3).
  *
- * P0-3: the official Typert gateway path (@deepseek-ai/dsh-api-gateway host
- * service, ctx key `typertGateway`) is wired here when the detected gateway
- * exposes a registration surface, keeping these paths as fallbacks.
+ * Host side, preference order:
+ *   1. dynamic-plugin run      -> `harness.handle(endpoint, fn)`
+ *   2. Typert gateway present  -> `typert.register(channel, endpoints)`
+ *   3. static (bundle) install -> Connection
+ *
+ * Connection has two registries and they are NOT interchangeable:
+ *
+ *   - `connection.fetch.register(route)` adds one exact route to the shared
+ *     `/api` dispatch table. It only touches the service's own map, so it
+ *     works from any fiber.
+ *   - `connection.rpc.handle(channel, handler)` mounts a physical prefix route
+ *     through `owner.webServer.register(route)`, where `owner` is the fiber
+ *     that READ the service. On 0.2.x every plugin fiber is a strict proxy: a
+ *     plugin whose `inject` is `['timer']` throws `cannot get property
+ *     "webServer" without inject` inside that registration, `effect()`
+ *     rethrows it, and the channel silently never mounts — observed as HTTP
+ *     405 on `/usage/*` with no host-side message. Adding `webServer` to the
+ *     plugin's static `inject` would "fix" it only for compositions that own a
+ *     web server, and would gate dynamic-plugin loads on a service they never
+ *     get, so the fetch registry is the correct seam for a bundle install.
+ *
+ * Therefore: register exact Fetch routes on the shared `/api` channel when
+ * that registry exists, and keep the legacy `/usage` prefix channel as a
+ * best-effort fallback for older hosts. The browser half calls the Fetch route
+ * first and falls back to the legacy channel on "route missing".
+ *
+ * Wire format of one Fetch route (POST `/api/usage/<endpoint>`):
+ *   request body  = JSON of the endpoint args (or empty for no args)
+ *   response body = `{ ok: true, value }` | `{ ok: false, error: { code, message } }`
+ * i.e. the same result shape the legacy RPC channel wraps, minus its envelope.
+ */
+/** Absolute logical channel owned by this plugin on pre-0.2 hosts. */
+export const USAGE_RPC_CHANNEL = '/usage';
+/** Shared-channel path prefix owned by this plugin (`/api` is Connection's mount). */
+export const USAGE_API_PREFIX = '/api/usage';
+/**
+ * Exact Fetch route path for one endpoint.
+ *
+ * @param {string} endpoint - endpoint name such as `query`.
+ * @returns {string} absolute path below `/api`, as `connection.fetch.register` requires.
+ */
+export function fetchRoutePath(endpoint) {
+    return USAGE_API_PREFIX + '/' + endpoint;
+}
+/**
+ * Failure result in the Connection RPC result shape.
+ *
+ * @param {string} message - human-readable failure.
+ * @param {string} [code] - stable error code.
+ * @returns {{ ok: false, error: { code: string, message: string, details: object } }} failure result.
+ */
+export function errorResult(message, code = 'internal') {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * Run one endpoint through the handler map, converting throws into results.
+ *
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
+ * @param {string} endpoint - endpoint name.
+ * @param {unknown} args - decoded endpoint arguments.
+ * @returns {Promise<{ ok: true, value: any } | { ok: false, error: object }>} RPC result.
+ */
+export async function dispatch(handlers, endpoint, args) {
+    const fn = handlers.get(endpoint);
+    if (fn === undefined)
+        return errorResult(`unknown endpoint: ${endpoint}`, 'bad-request');
+    try {
+        return { ok: true, value: await fn(args) };
+    }
+    catch (error) {
+        return errorResult(String((error && error.message) || error));
+    }
+}
+/**
+ * Build the Fetch-shaped handler for one exact route.
+ *
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
+ * @param {string} endpoint - endpoint name.
+ * @returns {(request: Request) => Promise<Response>} route handler.
+ */
+export function createFetchRoute(handlers, endpoint) {
+    return async function fetchRoute(request) {
+        let args = null;
+        const text = await request.text();
+        if (text.length > 0) {
+            try {
+                args = JSON.parse(text);
+            }
+            catch {
+                return Response.json(errorResult('request body is not JSON', 'bad-request'), { status: 400 });
+            }
+        }
+        return Response.json(await dispatch(handlers, endpoint, args));
+    };
+}
+/**
+ * Register every endpoint on the best transport this host offers.
+ *
+ * @param {any} ctx - host plugin context.
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
  */
 export function registerRPC(ctx, handlers) {
     const dynamicHarness = (typeof harness !== 'undefined' && harness && typeof harness.handle === 'function') ? harness : null;
@@ -48,22 +145,47 @@ export function registerRPC(ctx, handlers) {
     }
     // Static (bundle) installs: the `connection` service is provided
     // asynchronously by the client-connection plugin, so wait for it before
-    // registering the /usage channel (the official api-gateway pattern).
+    // registering (the official api-gateway pattern).
     ctx.inject(['connection'], (connectionCtx) => {
         const connection = connectionCtx.connection;
-        if (connection === undefined || connection.rpc === undefined)
+        if (connection === undefined || connection === null)
             return;
-        connection.rpc.handle('/usage', async (endpoint, args) => {
-            const fn = handlers.get(endpoint);
-            if (fn === undefined) {
-                return { ok: false, error: { code: 'bad-request', message: `unknown endpoint: ${endpoint}`, details: { issues: [] } } };
+        // 0.2+: exact Fetch routes on the shared /api channel. This is the path
+        // that actually mounts a route: it never reads `webServer`, so the strict
+        // fiber proxy cannot reject it.
+        const fetchRegistry = connection.fetch;
+        let mountedFetchRoutes = 0;
+        if (fetchRegistry !== undefined && typeof fetchRegistry.register === 'function') {
+            for (const endpoint of handlers.keys()) {
+                const path = fetchRoutePath(endpoint);
+                try {
+                    fetchRegistry.register({
+                        path,
+                        methods: ['POST'],
+                        requestBody: 'buffered',
+                        fetch: createFetchRoute(handlers, endpoint),
+                    });
+                    mountedFetchRoutes += 1;
+                }
+                catch (error) {
+                    console.warn(`[usage] failed to mount shared Fetch route ${path}: ${String((error && error.message) || error)}`);
+                }
             }
+        }
+        // Pre-0.2 hosts (and any composition that still exposes the prefix
+        // channel): the legacy /usage RPC bridge. On 0.2.x this throws inside
+        // effect() because the reading fiber owns no `webServer`; that is expected
+        // and already covered by the Fetch routes, so the failure stays local.
+        const rpcRegistry = connection.rpc;
+        if (rpcRegistry !== undefined && typeof rpcRegistry.handle === 'function') {
             try {
-                return { ok: true, value: await fn(args) };
+                rpcRegistry.handle(USAGE_RPC_CHANNEL, async (endpoint, args) => dispatch(handlers, endpoint, args), { authority: 'loopback' });
             }
             catch (error) {
-                return { ok: false, error: { code: 'internal', message: String((error && error.message) || error), details: {} } };
+                if (mountedFetchRoutes === 0) {
+                    console.warn(`[usage] failed to mount ${USAGE_RPC_CHANNEL} RPC channel: ${String((error && error.message) || error)}`);
+                }
             }
-        }, { authority: 'loopback' });
+        }
     });
 }