@shi-yangyang/dsh-token-dashboard 0.0.0-stage → 0.2.0

package/lib/host/server.d.ts

@@ -0,0 +1,30 @@
+/**
+ * HTTP surface for the dashboard.
+ *
+ * One same-origin, read-only prefix route:
+ *   GET /dsh-token-dashboard/stats    dashboard payload (ETag, ?refresh=1)
+ *   GET /dsh-token-dashboard/verify   fold vs official tokenUsage projection
+ *   GET /dsh-token-dashboard/requests paginated billed request log
+ *   GET /dsh-token-dashboard/prices   optional online list prices (explicit refresh)
+ *   GET /dsh-token-dashboard/health   liveness and revision
+ *
+ * The route reuses the Host Connection gate when the deployment publishes one,
+ * so a remote or logged-out peer is refused exactly like the Host API.
+ */
+import type { StatsPayload } from '../shared/types.js';
+import type { TokenAggregator } from './aggregate.js';
+import type { AggregatorSource } from './source.js';
+import type { PriceLookup } from './prices.js';
+import type { ConnectionLike, WebServerLike } from './types.js';
+/** Dependencies for the route registration. */
+export interface DashboardRoutesOptions {
+    server: WebServerLike;
+    aggregator: TokenAggregator;
+    source: AggregatorSource;
+    connection?: () => ConnectionLike | undefined;
+    prices?: PriceLookup;
+}
+/** Register the prefix route; returns its disposer. */
+export declare function registerDashboardRoutes(options: DashboardRoutesOptions): () => void;
+/** Type guard for tests: a payload carrying the required top-level fields. */
+export declare function isStatsPayload(value: unknown): value is StatsPayload;

package/lib/host/server.js

@@ -0,0 +1,177 @@
+/**
+ * HTTP surface for the dashboard.
+ *
+ * One same-origin, read-only prefix route:
+ *   GET /dsh-token-dashboard/stats    dashboard payload (ETag, ?refresh=1)
+ *   GET /dsh-token-dashboard/verify   fold vs official tokenUsage projection
+ *   GET /dsh-token-dashboard/requests paginated billed request log
+ *   GET /dsh-token-dashboard/prices   optional online list prices (explicit refresh)
+ *   GET /dsh-token-dashboard/health   liveness and revision
+ *
+ * The route reuses the Host Connection gate when the deployment publishes one,
+ * so a remote or logged-out peer is refused exactly like the Host API.
+ */
+import { API_PREFIX, API_VERSION } from '../shared/types.js';
+import { verifyAgainstProjection } from './verify.js';
+/** Register the prefix route; returns its disposer. */
+export function registerDashboardRoutes(options) {
+    return options.server.register({
+        kind: 'prefix',
+        path: API_PREFIX,
+        handler: async (req, res) => {
+            try {
+                if (refusedByHost(req, res, options.connection))
+                    return;
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const suffix = routeSuffix(url.pathname);
+                if (suffix === undefined) {
+                    sendError(res, 404, 'not-found', 'Unknown dashboard route.');
+                    return;
+                }
+                const method = (req.method ?? 'GET').toUpperCase();
+                if (method !== 'GET' && method !== 'HEAD') {
+                    res.setHeader('allow', 'GET, HEAD');
+                    sendError(res, 405, 'method-not-allowed', 'The dashboard API is read-only.');
+                    return;
+                }
+                const headOnly = method === 'HEAD';
+                if (suffix === '/health') {
+                    sendJson(res, 200, {
+                        ok: true,
+                        apiVersion: API_VERSION,
+                        initialized: options.aggregator.isInitialized,
+                        revision: options.aggregator.getRevision(),
+                    }, headOnly);
+                    return;
+                }
+                if (suffix === '/stats') {
+                    if (url.searchParams.get('refresh') === '1')
+                        await options.aggregator.refresh();
+                    else
+                        await options.aggregator.ensure();
+                    const payload = options.aggregator.stats();
+                    const etag = `W/"tdb-${payload.apiVersion}-${payload.revision}"`;
+                    if (matchesEtag(req, etag)) {
+                        res.writeHead(304, {
+                            etag,
+                            'cache-control': 'no-store',
+                        });
+                        res.end();
+                        return;
+                    }
+                    sendJson(res, 200, payload, headOnly, { etag });
+                    return;
+                }
+                if (suffix === '/requests') {
+                    if (url.searchParams.get('refresh') === '1')
+                        await options.aggregator.refresh();
+                    else
+                        await options.aggregator.ensure();
+                    const offset = Number(url.searchParams.get('offset') ?? '0');
+                    const limit = Number(url.searchParams.get('limit') ?? '24');
+                    sendJson(res, 200, options.aggregator.requestPage(offset, limit), headOnly);
+                    return;
+                }
+                if (suffix === '/prices') {
+                    if (options.prices === undefined) {
+                        sendError(res, 503, 'prices-unavailable', 'Online prices are not configured.');
+                        return;
+                    }
+                    const rawModels = url.searchParams.get('models') ?? '';
+                    const models = [...new Set(rawModels
+                            .split(',')
+                            .map(model => model.trim())
+                            .filter(model => model !== '' && model.length <= 160))]
+                        .slice(0, 100);
+                    try {
+                        const payload = await options.prices.lookup(models, url.searchParams.get('refresh') === '1');
+                        sendJson(res, 200, payload, headOnly);
+                    }
+                    catch {
+                        sendError(res, 502, 'prices-unavailable', 'Online prices are unavailable.');
+                    }
+                    return;
+                }
+                if (suffix === '/verify') {
+                    await options.aggregator.ensure();
+                    const limit = Number(url.searchParams.get('limit') ?? '40');
+                    const report = await verifyAgainstProjection(options.source, options.aggregator, limit);
+                    sendJson(res, 200, report, headOnly);
+                    return;
+                }
+                sendError(res, 404, 'not-found', 'Unknown dashboard route.');
+            }
+            catch (error) {
+                console.warn(`[dsh-token-dashboard] request failed: ${safeErrorName(error)}`);
+                if (!res.headersSent) {
+                    sendError(res, 500, 'internal', 'The token dashboard could not read session history.');
+                }
+            }
+        },
+    });
+}
+function routeSuffix(pathname) {
+    const index = pathname.lastIndexOf(API_PREFIX);
+    if (index === -1)
+        return undefined;
+    if (index !== 0 && pathname[index - 1] !== '/')
+        return undefined;
+    const suffix = pathname.slice(index + API_PREFIX.length);
+    if (suffix === '' || suffix === '/')
+        return '/';
+    return `/${suffix.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+function refusedByHost(req, res, connection) {
+    let status;
+    try {
+        status = connection?.()?.requestRejection?.(req);
+    }
+    catch {
+        status = 403;
+    }
+    if (typeof status !== 'number')
+        return false;
+    res.writeHead(status, { 'cache-control': 'no-store' });
+    res.end();
+    return true;
+}
+function matchesEtag(req, etag) {
+    const raw = req.headers['if-none-match'];
+    const value = Array.isArray(raw) ? raw.join(',') : raw;
+    if (typeof value !== 'string')
+        return false;
+    return value.split(',').map(part => part.trim()).includes(etag);
+}
+function sendJson(res, status, payload, headOnly = false, extra = {}) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+        ...extra,
+    });
+    if (headOnly)
+        res.end();
+    else
+        res.end(body);
+}
+function sendError(res, status, code, message) {
+    sendJson(res, status, { error: { code, message } });
+}
+function safeErrorName(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return typeof code === 'string' ? `${error.name}:${code}` : error.name;
+    }
+    return 'UnknownError';
+}
+/** Type guard for tests: a payload carrying the required top-level fields. */
+export function isStatsPayload(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const record = value;
+    return record.apiVersion === API_VERSION
+        && typeof record.revision === 'number'
+        && Array.isArray(record.days)
+        && Array.isArray(record.sessionRows);
+}

package/lib/host/source.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Host adapter over the official DSH services:
+ * `sessionPersistence.list()/open()` for durable logs, `sessions.list()` for
+ * live sessions, and `sessionQuery.observeSession()` for the diagnostic
+ * cross-check against token-meter's `tokenUsage` projection.
+ *
+ * The adapter is read-only. It never appends, rewrites, flushes, or deletes a
+ * session log.
+ */
+import type { TokenBuckets } from '../shared/types.js';
+import type { HostServiceAccess, RawSessionEvent, SessionHeaderLike } from './types.js';
+/** One session visible to the aggregator, live or persisted. */
+export interface SessionDescriptor {
+    id: string;
+    header: SessionHeaderLike;
+    live: boolean;
+    /** Live: total event count (`session.seq`). Persisted: `eventCount` when known. */
+    seq: number;
+    revision?: string;
+    eventCount?: number;
+    inheritedEventCount: number;
+}
+/** A full or tail read of one session log. */
+export interface SessionReadResult {
+    header: SessionHeaderLike;
+    inheritedEventCount: number;
+    events: readonly RawSessionEvent[];
+}
+/** The aggregator's data source. Tests provide a fake implementation. */
+export interface AggregatorSource {
+    list(): Promise<SessionDescriptor[]>;
+    read(descriptor: SessionDescriptor, from: number): Promise<SessionReadResult>;
+    projectUsage?(id: string): Promise<TokenBuckets | undefined>;
+    projectLabel?(cwd: string | undefined): string;
+}
+/** Build the DSH-backed source. */
+export declare function createDshSource(access: HostServiceAccess): AggregatorSource;

package/lib/host/source.js

@@ -0,0 +1,179 @@
+/**
+ * Host adapter over the official DSH services:
+ * `sessionPersistence.list()/open()` for durable logs, `sessions.list()` for
+ * live sessions, and `sessionQuery.observeSession()` for the diagnostic
+ * cross-check against token-meter's `tokenUsage` projection.
+ *
+ * The adapter is read-only. It never appends, rewrites, flushes, or deletes a
+ * session log.
+ */
+/** Build the DSH-backed source. */
+export function createDshSource(access) {
+    let workspaceTitles = new Map();
+    function persistence() {
+        const service = access.persistence();
+        if (service === undefined)
+            throw new Error('sessionPersistence is unavailable');
+        return service;
+    }
+    function refreshWorkspaces() {
+        const next = new Map();
+        try {
+            for (const workspace of access.workspaces()?.list() ?? []) {
+                if (typeof workspace.path === 'string' && typeof workspace.title === 'string' && workspace.title.trim() !== '') {
+                    next.set(trimTrailingSeparators(workspace.path), workspace.title);
+                }
+            }
+        }
+        catch {
+            // A workspace registry failure only costs nicer project labels.
+        }
+        workspaceTitles = next;
+    }
+    return {
+        async list() {
+            refreshWorkspaces();
+            const persisted = await persistence().list();
+            const descriptors = new Map();
+            for (const snapshot of persisted) {
+                const descriptor = fromSnapshot(snapshot);
+                if (descriptor !== undefined)
+                    descriptors.set(descriptor.id, descriptor);
+            }
+            for (const live of access.sessions()?.list() ?? []) {
+                const previous = descriptors.get(live.id);
+                const inherited = Math.max(0, Math.trunc(Number(live.inheritedEventCount) || 0));
+                const seq = Math.max(0, Math.trunc(Number(live.seq) || 0));
+                descriptors.set(live.id, {
+                    id: live.id,
+                    header: live.header,
+                    live: true,
+                    seq,
+                    inheritedEventCount: inherited,
+                    ...(previous?.revision === undefined ? {} : { revision: previous.revision }),
+                    ...(previous?.eventCount === undefined ? {} : { eventCount: previous.eventCount }),
+                });
+            }
+            return [...descriptors.values()];
+        },
+        async read(descriptor, from) {
+            if (descriptor.live) {
+                const live = access.sessions()?.get(descriptor.id);
+                if (live !== undefined) {
+                    const total = Math.max(0, Math.trunc(Number(live.seq) || 0));
+                    const start = Math.max(0, Math.min(Math.trunc(from), total));
+                    const events = start >= total ? [] : live.snapshotEvents(start, total);
+                    return {
+                        header: live.header,
+                        inheritedEventCount: Math.max(0, Math.trunc(Number(live.inheritedEventCount) || 0)),
+                        events,
+                    };
+                }
+                // The session was disposed between list() and read(): fall through to
+                // the durable log, which it has already flushed by disposal.
+            }
+            const handle = await persistence().open(descriptor.id, 'read');
+            try {
+                const result = await handle.read(Math.max(0, Math.trunc(from)));
+                return {
+                    header: handle.header,
+                    inheritedEventCount: Math.max(0, Math.trunc(Number(handle.inheritedEventCount) || 0)),
+                    events: result.events,
+                };
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        async projectUsage(id) {
+            const query = access.sessionQuery();
+            if (query === undefined)
+                return undefined;
+            let observation;
+            try {
+                observation = await query.observeSession(id, { projectionMode: 'all' });
+                const values = asRecord(asRecord(observation.projections)?.values);
+                const usage = asRecord(values?.tokenUsage);
+                if (usage === undefined)
+                    return undefined;
+                return {
+                    uncachedInputTokens: count(usage.uncachedInputTokens),
+                    cacheReadTokens: count(usage.cacheReadTokens),
+                    cacheWriteTokens: count(usage.cacheWriteTokens),
+                    outputTokens: count(usage.outputTokens),
+                };
+            }
+            finally {
+                disposeObservation(observation);
+            }
+        },
+        projectLabel(cwd) {
+            if (cwd === undefined || cwd.trim() === '')
+                return '';
+            const key = trimTrailingSeparators(cwd);
+            return workspaceTitles.get(key) ?? baseName(key);
+        },
+    };
+}
+function fromSnapshot(snapshot) {
+    const header = snapshot.header;
+    if (header === undefined || typeof header.id !== 'string' || header.id === '')
+        return undefined;
+    const eventCount = typeof snapshot.eventCount === 'number' && Number.isFinite(snapshot.eventCount)
+        ? Math.max(0, Math.trunc(snapshot.eventCount))
+        : 0;
+    return {
+        id: header.id,
+        header,
+        live: false,
+        seq: eventCount,
+        eventCount,
+        inheritedEventCount: 0,
+        revision: typeof snapshot.revision === 'string' ? snapshot.revision : String(snapshot.revision),
+    };
+}
+function disposeObservation(observation) {
+    if (observation === undefined)
+        return;
+    const symbol = Symbol.dispose;
+    if (symbol !== undefined) {
+        const candidate = observation;
+        const disposer = candidate[symbol];
+        if (typeof disposer === 'function') {
+            try {
+                disposer.call(observation);
+            }
+            catch {
+                // The lease is best-effort released; a failed release must not mask
+                // the projection result or replace the operation's own error.
+            }
+            return;
+        }
+    }
+    if (typeof observation.dispose === 'function') {
+        try {
+            observation.dispose();
+        }
+        catch {
+            // See above.
+        }
+    }
+}
+function trimTrailingSeparators(value) {
+    const trimmed = value.replace(/[\\/]+$/, '');
+    return trimmed === '' ? value : trimmed;
+}
+function baseName(value) {
+    const parts = trimTrailingSeparators(value).split(/[\\/]/);
+    return parts[parts.length - 1] || value;
+}
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function count(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        return 0;
+    return Math.round(value);
+}

package/lib/host/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Structural views of the Host services this plugin consumes.
+ *
+ * They mirror the published DSH contracts the plugin was verified against
+ * (`ctx.sessionPersistence`, `ctx.sessions`, `ctx.sessionQuery`,
+ * `ctx.webServer`, `ctx.connection`, `ctx.workspaceRegistry`) without importing
+ * an implementation package. The installed Harness remains the authority.
+ */
+/** One durable session event, as exposed by the persistence handle. */
+export interface RawSessionEvent {
+    readonly type: string;
+    readonly seq: number;
+    readonly time: number;
+    readonly data?: unknown;
+    readonly surfaceOp?: unknown;
+    readonly ignorable?: true;
+}
+/** The immutable session header fields this plugin reads. */
+export interface SessionHeaderLike {
+    readonly id: string;
+    readonly createdAt?: number;
+    readonly cwd?: string;
+    readonly parentSession?: string;
+    readonly isSeeded?: boolean;
+    readonly origin?: 'subagent';
+    readonly delegationDepth?: number;
+    readonly agentPreset?: string;
+}
+/** Provider-reported usage, as logged on assistant events. */
+export interface UsageSample {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly totalTokens?: number;
+    readonly reasoningTokens?: number;
+}
+/** Persistence snapshot (`ctx.sessionPersistence.list()`). */
+export interface PersistenceSnapshot {
+    readonly header: SessionHeaderLike;
+    readonly revision: string;
+    readonly eventCount?: number;
+    readonly sizeBytes?: number;
+    readonly formatStatus?: string;
+}
+/** Read-only persistence handle, narrowed to what this plugin calls. */
+export interface PersistenceHandle {
+    readonly id: string;
+    readonly header: SessionHeaderLike;
+    readonly inheritedEventCount: number;
+    read(offset?: number, length?: number): Promise<{
+        readonly events: readonly RawSessionEvent[];
+    }>;
+    close(): Promise<void>;
+}
+/** The persistence service face. */
+export interface SessionPersistenceLike {
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly PersistenceSnapshot[]>;
+    open(id: string, access: 'read' | 'write', options?: {
+        signal?: AbortSignal;
+    }): Promise<PersistenceHandle>;
+}
+/** A live in-memory Session (`ctx.sessions.list()`). */
+export interface LiveSessionLike {
+    readonly id: string;
+    readonly header: SessionHeaderLike;
+    readonly inheritedEventCount: number;
+    readonly seq: number;
+    snapshotEvents(from: number, to: number): readonly RawSessionEvent[];
+}
+/** Live session store. */
+export interface SessionsLike {
+    list(): readonly LiveSessionLike[];
+    get(id: string): LiveSessionLike | undefined;
+}
+/** A session observation lease from `ctx.sessionQuery.observeSession()`. */
+export interface SessionObservationLike {
+    readonly projections?: {
+        readonly values?: unknown;
+    };
+    dispose?: () => void;
+}
+/** Query service face used only by the diagnostic verification endpoint. */
+export interface SessionQueryLike {
+    observeSession(id: string, options?: {
+        readonly projectionMode?: 'all' | 'none';
+        readonly signal?: AbortSignal;
+    }): Promise<SessionObservationLike>;
+}
+/** Workspace registry entry used for project labels. */
+export interface WorkspaceLike {
+    readonly id?: string;
+    readonly title?: string;
+    readonly path?: string;
+}
+export interface WorkspaceRegistryLike {
+    list(): readonly WorkspaceLike[];
+}
+/** The Host connection gate. */
+export interface ConnectionLike {
+    requestRejection?(request: unknown): number | undefined;
+}
+/** The web server route registration face. */
+export interface WebServerLike {
+    register(route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: HttpRequestLike, res: HttpResponseLike) => void | Promise<void>;
+    }): () => void;
+}
+/** Minimal HTTP request surface used by the route handler. */
+export interface HttpRequestLike {
+    readonly method?: string;
+    readonly url?: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+}
+/** Minimal HTTP response surface used by the route handler. */
+export interface HttpResponseLike {
+    statusCode: number;
+    readonly headersSent?: boolean;
+    setHeader(name: string, value: string): void;
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    end(body?: string): void;
+}
+/** Services looked up at call time, so late mounts are not captured as absent. */
+export interface HostServiceAccess {
+    persistence(): SessionPersistenceLike | undefined;
+    sessions(): SessionsLike | undefined;
+    sessionQuery(): SessionQueryLike | undefined;
+    workspaces(): WorkspaceRegistryLike | undefined;
+}

package/lib/host/types.js

@@ -0,0 +1,9 @@
+/**
+ * Structural views of the Host services this plugin consumes.
+ *
+ * They mirror the published DSH contracts the plugin was verified against
+ * (`ctx.sessionPersistence`, `ctx.sessions`, `ctx.sessionQuery`,
+ * `ctx.webServer`, `ctx.connection`, `ctx.workspaceRegistry`) without importing
+ * an implementation package. The installed Harness remains the authority.
+ */
+export {};

package/lib/host/verify.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Diagnostic cross-check: fold result vs token-meter's official `tokenUsage`
+ * projection.
+ *
+ * `ctx.sessionQuery.observeSession(id, { projectionMode: 'all' })` exposes the
+ * registered projection values for a persisted session without publishing it.
+ * The check reports only ids and four-field buckets; no event content, title,
+ * or cwd is returned.
+ */
+import type { VerifyReport } from '../shared/types.js';
+import type { TokenAggregator } from './aggregate.js';
+import type { AggregatorSource } from './source.js';
+/** Verify up to `limit` sessions (default 40, hard cap 200). */
+export declare function verifyAgainstProjection(source: AggregatorSource, aggregator: TokenAggregator, limit?: number): Promise<VerifyReport>;

package/lib/host/verify.js

@@ -0,0 +1,79 @@
+/**
+ * Diagnostic cross-check: fold result vs token-meter's official `tokenUsage`
+ * projection.
+ *
+ * `ctx.sessionQuery.observeSession(id, { projectionMode: 'all' })` exposes the
+ * registered projection values for a persisted session without publishing it.
+ * The check reports only ids and four-field buckets; no event content, title,
+ * or cwd is returned.
+ */
+import { bucketsEqual } from '../shared/model.js';
+import { API_VERSION } from '../shared/types.js';
+/** Verify up to `limit` sessions (default 40, hard cap 200). */
+export async function verifyAgainstProjection(source, aggregator, limit = 40) {
+    const report = {
+        apiVersion: API_VERSION,
+        checked: 0,
+        matched: 0,
+        mismatched: 0,
+        unsupported: 0,
+        matchedBasis: { own: 0, allLog: 0, none: 0 },
+        details: [],
+        generatedAt: Date.now(),
+    };
+    if (source.projectUsage === undefined) {
+        report.unsupported = aggregator.sessionsForVerification().length;
+        return report;
+    }
+    const sessions = aggregator.sessionsForVerification().slice(0, clampLimit(limit));
+    const concurrency = 2;
+    let cursor = 0;
+    const worker = async () => {
+        for (;;) {
+            const session = sessions[cursor];
+            cursor += 1;
+            if (session === undefined)
+                return;
+            let official;
+            try {
+                official = await source.projectUsage?.(session.id);
+            }
+            catch {
+                official = undefined;
+            }
+            report.checked += 1;
+            if (official === undefined) {
+                report.unsupported += 1;
+                continue;
+            }
+            const match = bucketsEqual(official, session.own)
+                ? 'own'
+                : bucketsEqual(official, session.allLog)
+                    ? 'allLog'
+                    : 'none';
+            if (match === 'none') {
+                report.mismatched += 1;
+                report.matchedBasis.none += 1;
+            }
+            else {
+                report.matched += 1;
+                report.matchedBasis[match] += 1;
+            }
+            report.details.push({
+                sessionId: session.id,
+                official,
+                own: session.own,
+                allLog: session.allLog,
+                inheritedEventCount: session.inheritedEventCount,
+                match,
+            });
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, Math.max(1, sessions.length)) }, () => worker()));
+    return report;
+}
+function clampLimit(limit) {
+    if (!Number.isFinite(limit))
+        return 40;
+    return Math.min(200, Math.max(1, Math.trunc(limit)));
+}