@gamegeek-saikel/dsh-cost-meter 0.1.0

package/lib/types/index.js

@@ -0,0 +1,401 @@
+/**
+ * dsh-cost-meter host half: serves the DeepSeek account balance
+ * (official `GET /user/balance`), the pricebook (persisted, snapshot-anchored
+ * per-model pricing over the official page / built-in fallback / OpenRouter
+ * chain), and drives the `sessionCost` projection that folds every usage
+ * event into an immutable per-step cost ledger.
+ *
+ * The API key resolves per refresh through the credential seam; the balance
+ * is cached for `refreshMs` to stay polite to the provider's rate limits;
+ * the pricebook refresh cadence is `pricingRefreshHours`. The `/cost-meter`
+ * route serves the balance + pricebook view (GET) and applies settings
+ * mutations and manual refreshes (POST, trust-fenced like the balance route).
+ *
+ * @module @gamegeek-saikel/dsh-cost-meter
+ */
+import z from '@deepseek-ai/schemastery';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { DEFAULT_ALIASES, DEFAULT_CACHE_READ_DISCOUNT, DEFAULT_FX_RATE, DEFAULT_SNAPSHOT_HISTORY_LIMIT, FX_API_URL, OPENROUTER_MODELS_URL, PricebookHandle, } from "./pricebook.js";
+import { sessionCostProjection } from "./session-cost-projection.js";
+import { collectSubagentCosts } from "./subagent-cost.js";
+export * from "./pricing.js";
+export * from "./pricebook.js";
+export * from "./session-cost-projection.js";
+export * from "./subagent-cost.js";
+/** Stable Cordis plugin name. */
+export const name = 'cost-meter';
+/** Services required before the route and the projection can register. */
+export const inject = ['webServer', 'sessionProjections'];
+/** Public DeepSeek API base; the internal endpoint comes from config `baseURL`. */
+export const PUBLIC_BASE_URL = 'https://api.deepseek.com';
+/** Default credential reference, matching the llm-deepseek adapter. */
+export const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
+/** How long a successful balance snapshot stays fresh (milliseconds). */
+export const DEFAULT_REFRESH_MS = 60_000;
+/** How long a failed refresh stays cached before retrying (milliseconds). */
+const FAILED_REFRESH_MS = 10_000;
+/** Per-request timeout for the provider balance call (milliseconds). */
+const BALANCE_TIMEOUT_MS = 10_000;
+/** Default cadence for re-fetching the official pricing page (hours). */
+export const DEFAULT_PRICING_REFRESH_HOURS = 6;
+/** Max POST body accepted by the settings route (bytes). */
+const MAX_BODY_BYTES = 256 * 1024;
+const modelPriceSchema = z.object({
+    single: z.object({
+        cacheReadPerMillion: z.number().min(0),
+        inputPerMillion: z.number().min(0),
+        outputPerMillion: z.number().min(0),
+    }),
+    offPeak: z.object({
+        cacheReadPerMillion: z.number().min(0),
+        inputPerMillion: z.number().min(0),
+        outputPerMillion: z.number().min(0),
+    }),
+    peak: z.object({
+        cacheReadPerMillion: z.number().min(0),
+        inputPerMillion: z.number().min(0),
+        outputPerMillion: z.number().min(0),
+    }),
+});
+export const Config = z.object({
+    apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+    baseURL: z.string().default(PUBLIC_BASE_URL),
+    refreshMs: z.natural().min(1000).default(DEFAULT_REFRESH_MS),
+    pricingRefreshHours: z.number().min(1).default(DEFAULT_PRICING_REFRESH_HOURS),
+    trustedHosts: z.array(z.string()).default([]),
+    fxApiUrl: z.string().default(FX_API_URL),
+    defaultFxRate: z.number().min(0.001).default(DEFAULT_FX_RATE),
+    openRouterModelsUrl: z.string().default(OPENROUTER_MODELS_URL),
+    openRouterEnabled: z.boolean().default(true),
+    snapshotHistoryLimit: z.natural().min(1).default(DEFAULT_SNAPSHOT_HISTORY_LIMIT),
+    overrides: z.dict(modelPriceSchema, z.string()).default({}),
+    aliases: z.dict(z.string(), z.string()).default({ ...DEFAULT_ALIASES }),
+    cacheReadDiscount: z.number().min(0).max(1).default(DEFAULT_CACHE_READ_DISCOUNT),
+    fxMode: z.union(['auto', 'manual']).default('auto'),
+    manualRate: z.number().min(0.001).default(DEFAULT_FX_RATE),
+    balanceEnabled: z.boolean().default(true),
+});
+/** Normalized authority of a Host-header value, or undefined when unparsable. */
+function parseAuthority(authority) {
+    try {
+        // http: is a WHATWG "special scheme": parsing yields a non-empty hostname or throws.
+        return new URL(`http://${authority}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a normalized URL hostname names the local loopback authority.
+ * @param hostname - WHATWG URL hostname (IPv6 literals retain brackets).
+ * @returns true for localhost, IPv6 loopback, or any IPv4 address in 127/8.
+ */
+export function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '[::1]')
+        return true;
+    const parts = hostname.split('.');
+    return parts.length === 4
+        && parts[0] === '127'
+        && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/**
+ * Browser-trust fence for the balance route, mirroring the /api fence: the
+ * Host header is the one header DNS rebinding cannot forge, and loopback or
+ * a declared trusted authority passes.
+ * @param headers - request headers.
+ * @param trustedHosts - non-loopback authorities this deployment serves.
+ * @returns true when the request Host is ours.
+ */
+export function isTrustedRequest(headers, trustedHosts) {
+    const host = headers.host;
+    if (typeof host !== 'string' || host.length === 0)
+        return false;
+    const hostUrl = parseAuthority(host);
+    if (hostUrl === undefined)
+        return false;
+    if (isLoopbackHostname(hostUrl.hostname))
+        return true;
+    return trustedHosts.some((entry) => {
+        const entryUrl = parseAuthority(entry);
+        return entryUrl !== undefined && entryUrl.host === hostUrl.host;
+    });
+}
+/**
+ * Resolve the API key for one refresh: the credential seam first, the
+ * process environment as fallback when no seam is composed.
+ * @param ctx - host context.
+ * @param env - the credential reference name.
+ * @returns the resolved key, or undefined when absent everywhere.
+ */
+export async function resolveApiKey(ctx, env) {
+    const credentials = ctx.get('credentials');
+    if (credentials !== undefined) {
+        const hit = await credentials.resolve(credentialRef(env));
+        if (hit !== undefined && hit.value.length > 0)
+            return hit.value;
+    }
+    const ambient = process.env[env];
+    return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
+}
+/**
+ * Parse the first balance row, converting the provider's decimal strings to
+ * numbers.
+ * @param wire - the parsed provider response.
+ * @returns the first row, or null when the response carried no rows.
+ */
+export function pickBalanceInfo(wire) {
+    const info = wire.balance_infos?.[0];
+    if (info === undefined)
+        return null;
+    return {
+        currency: info.currency,
+        total: Number(info.total_balance),
+        granted: Number(info.granted_balance ?? 0),
+        toppedUp: Number(info.topped_up_balance ?? 0),
+    };
+}
+/**
+ * One provider balance call: resolve the key, GET /user/balance, and fold
+ * the result into a {@link BalanceSnapshot}. Never throws — every failure
+ * becomes an ok:false snapshot.
+ * @param ctx - host context.
+ * @param config - resolved plugin facts.
+ * @returns the folded snapshot.
+ */
+export async function fetchBalance(ctx, config) {
+    const key = await resolveApiKey(ctx, config.apiKeyEnv);
+    if (key === undefined) {
+        return {
+            ok: false,
+            code: 'MISSING_CREDENTIAL',
+            message: `cost-meter: no API key for "${config.apiKeyEnv}"; store it through the credentials service or export it in the launching environment`,
+        };
+    }
+    let response;
+    try {
+        response = await fetch(`${config.baseURL}/user/balance`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(BALANCE_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: 'NETWORK',
+            message: `cost-meter: balance request failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!response.ok) {
+        return {
+            ok: false,
+            code: `HTTP_${response.status}`,
+            message: `cost-meter: balance endpoint answered ${response.status} ${response.statusText}`,
+        };
+    }
+    let wire;
+    try {
+        wire = await response.json();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: 'INVALID_RESPONSE',
+            message: `cost-meter: balance body unparsable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return {
+        ok: true,
+        isAvailable: wire.is_available === true,
+        balance: pickBalanceInfo(wire),
+        fetchedAt: Date.now(),
+    };
+}
+/** Read a bounded JSON request body. */
+async function readBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const part = chunk;
+        total += part.length;
+        if (total > MAX_BODY_BYTES)
+            throw new Error('body too large');
+        chunks.push(part);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text.length === 0)
+        return {};
+    return JSON.parse(text);
+}
+/** The `cost-meter` settings namespace (plugin configuration page). */
+export const SETTINGS_NAMESPACE = settingsNamespace('cost-meter');
+/**
+ * Mount the plugin: open the pricebook domain, refresh every remote source,
+ * register the `sessionCost` projection, register the /cost-meter
+ * route (GET view + POST settings/refresh), and keep the balance and the
+ * official pricing fresh.
+ * @param ctx - host context.
+ * @param config - plugin config (schema defaults applied by the Loader).
+ */
+export async function apply(ctx, config) {
+    const resolved = {
+        apiKeyEnv: config?.apiKeyEnv ?? DEFAULT_API_KEY_ENV,
+        baseURL: config?.baseURL ?? PUBLIC_BASE_URL,
+        refreshMs: config?.refreshMs ?? DEFAULT_REFRESH_MS,
+        pricingRefreshHours: config?.pricingRefreshHours ?? DEFAULT_PRICING_REFRESH_HOURS,
+        trustedHosts: config?.trustedHosts ?? [],
+        fxApiUrl: config?.fxApiUrl ?? FX_API_URL,
+        defaultFxRate: config?.defaultFxRate ?? DEFAULT_FX_RATE,
+        openRouterModelsUrl: config?.openRouterModelsUrl ?? OPENROUTER_MODELS_URL,
+        openRouterEnabled: config?.openRouterEnabled ?? true,
+        snapshotHistoryLimit: config?.snapshotHistoryLimit ?? DEFAULT_SNAPSHOT_HISTORY_LIMIT,
+    };
+    const pricebookConfig = {
+        fxApiUrl: resolved.fxApiUrl,
+        defaultFxRate: resolved.defaultFxRate,
+        openRouterModelsUrl: resolved.openRouterModelsUrl,
+        openRouterEnabled: resolved.openRouterEnabled,
+        snapshotHistoryLimit: resolved.snapshotHistoryLimit,
+    };
+    // ── Pricebooks: load persisted state, then refresh every remote source. ──
+    const pricebookCny = new PricebookHandle(ctx, pricebookConfig, undefined, 'CNY');
+    const pricebookUsd = new PricebookHandle(ctx, pricebookConfig, undefined, 'USD');
+    await Promise.all([pricebookCny.init(), pricebookUsd.init()]);
+    await Promise.all([pricebookCny.refresh(), pricebookUsd.refresh()]);
+    ctx.effect(() => () => {
+        void pricebookCny.close();
+        void pricebookUsd.close();
+    }, 'cost-meter: pricebook domains');
+    // ── Plugin configuration section: the settings page renders the standard
+    //  card; every resolved change is applied to both pricebooks and re-anchors.
+    let currentSettings = () => config ?? {};
+    installSettingsSection(ctx, SETTINGS_NAMESPACE, Config, (config ?? {}), {
+        setSource: (source) => {
+            currentSettings = source;
+        },
+        onChange: () => {
+            const settings = currentSettings();
+            pricebookCny.applySettings(settings);
+            pricebookUsd.applySettings(settings);
+        },
+    });
+    // ── sessionCost projections: anchored per-step ledgers for CNY and USD. ──
+    ctx.effect(() => ctx.sessionProjections.register(sessionCostProjection(pricebookCny, 'sessionCost')), 'cost-meter: sessionCost projection');
+    ctx.effect(() => ctx.sessionProjections.register(sessionCostProjection(pricebookUsd, 'sessionCostUsd')), 'cost-meter: sessionCostUsd projection');
+    // ── Balance: cached refresh, one in-flight at a time. ──
+    let lastBalance;
+    let inflight;
+    const refresh = () => {
+        const now = Date.now();
+        const ttl = lastBalance === undefined
+            ? 0
+            : lastBalance.snapshot.ok ? resolved.refreshMs : FAILED_REFRESH_MS;
+        if (lastBalance !== undefined && now - lastBalance.at < ttl) {
+            return Promise.resolve(lastBalance.snapshot);
+        }
+        if (inflight === undefined) {
+            inflight = fetchBalance(ctx, resolved).then((snapshot) => {
+                lastBalance = { at: Date.now(), snapshot };
+                inflight = undefined;
+                return snapshot;
+            }, (error) => {
+                inflight = undefined;
+                return {
+                    ok: false,
+                    code: 'INTERNAL',
+                    message: `cost-meter: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            });
+        }
+        return inflight;
+    };
+    // ── Pricing: refresh on startup and on the configured cadence. ──
+    const pricingTimer = setInterval(() => {
+        void pricebookCny.refresh();
+        void pricebookUsd.refresh();
+    }, resolved.pricingRefreshHours * 3_600_000);
+    pricingTimer.unref?.();
+    ctx.effect(() => () => clearInterval(pricingTimer), 'cost-meter: pricing refresh timer');
+    const respond = (res, status, body) => {
+        res.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+        });
+        res.end(JSON.stringify(body));
+    };
+    /** Parse the `session` query parameter (the requesting session id). */
+    const sessionOf = (req) => {
+        try {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            const value = url.searchParams.get('session');
+            return value === null || value.length === 0 ? undefined : value;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /** Parse the `currency` query parameter; defaults to CNY. */
+    const currencyOf = (req) => {
+        try {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            return url.searchParams.get('currency') === 'USD' ? 'USD' : 'CNY';
+        }
+        catch {
+            return 'CNY';
+        }
+    };
+    const buildResponse = async (rootSessionId, currency) => {
+        const agents = ctx.get('agents');
+        const sessionsStore = ctx.get('sessions');
+        const pricebook = currency === 'USD' ? pricebookUsd : pricebookCny;
+        const projectionKey = currency === 'USD' ? 'sessionCostUsd' : 'sessionCost';
+        const subagents = rootSessionId === undefined || agents === undefined || sessionsStore === undefined
+            ? []
+            : collectSubagentCosts(rootSessionId, agents, sessionsStore, ctx.sessionProjections, projectionKey);
+        return {
+            balance: await refresh(),
+            pricebook: pricebook.view(),
+            subagents,
+        };
+    };
+    const route = {
+        kind: 'exact',
+        path: '/cost-meter',
+        handler: async (req, res) => {
+            if (req.method !== 'GET' && req.method !== 'POST') {
+                res.writeHead(405, { allow: 'GET, POST' });
+                res.end('method not allowed');
+                return;
+            }
+            if (!isTrustedRequest(req.headers, resolved.trustedHosts)) {
+                res.writeHead(403);
+                res.end('forbidden');
+                return;
+            }
+            if (req.method === 'POST') {
+                let action;
+                try {
+                    const body = await readBody(req);
+                    if (body.action !== 'refresh')
+                        throw new Error(`unknown action "${String(body.action)}"`);
+                    action = { action: 'refresh' };
+                }
+                catch (error) {
+                    respond(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                    return;
+                }
+                try {
+                    await Promise.all([pricebookCny.refresh(), pricebookUsd.refresh()]);
+                }
+                catch (error) {
+                    respond(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                    return;
+                }
+                respond(res, 200, await buildResponse(sessionOf(req), currencyOf(req)));
+                return;
+            }
+            respond(res, 200, await buildResponse(sessionOf(req), currencyOf(req)));
+        },
+    };
+    ctx.effect(() => ctx.webServer.register(route), 'cost-meter: /cost-meter route');
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@gamegeek-saikel/dsh-cost-meter`.
+ * @module @gamegeek-saikel/dsh-cost-meter/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "cost-meter-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,yBAAyB,CAAA;AAC1C,0DAA0D;AAC1D,eAAO,MAAM,MAAM,UAAiB,CAAA;AAyBpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -0,0 +1,38 @@
+/**
+ * Package-owned invariant companion for `@gamegeek-saikel/dsh-cost-meter`.
+ * @module @gamegeek-saikel/dsh-cost-meter/invariant
+ */
+const PACKAGE_NAME = '@gamegeek-saikel/dsh-cost-meter';
+/** Cordis companion plugin name. */
+export const name = 'cost-meter-invariant';
+/** Service required before the companion can register. */
+export const inject = ['invariants'];
+/**
+ * Route-disposer symmetry: after the owning fiber of the /cost-meter
+ * route unloads, the webserver must no longer answer that path. The probe
+ * cycle registers and disposes twice on a reserved path — a leftover from
+ * the first cycle makes the second register throw the duplicate error,
+ * exactly the asymmetry this package would otherwise share with its host.
+ */
+const install = (ctx, fail) => {
+    ctx.on('internal/plugin', () => {
+        const server = ctx.get('webServer');
+        if (server === undefined)
+            return; // no webserver row in this composition
+        const probe = { kind: 'exact', path: '/__dsh_fare_meter_invariant_probe__', handler: () => { } };
+        try {
+            server.register(probe)();
+            server.register(probe)();
+        }
+        catch {
+            fail('cost-meter webserver route disposer left a route registered — route tables and fiber lifecycles diverged');
+        }
+    }, { global: true });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */