@jxgame2020/dsh-token-quota 0.1.0

package/lib/types/client/index.js

@@ -0,0 +1,232 @@
+import { createTokenQuotaPanelStore } from "./store.js";
+import { TokenQuotaPanel } from "./TokenQuotaPanel.js";
+import { en, zh } from "./locales.js";
+export { mergeModelRows } from "./store.js";
+/** Dictionary namespace owning the panel copy. */
+const NS = 'token-quota';
+/** Settings namespace the Host quota package owns. */
+const TOKEN_QUOTA_NAMESPACE = 'token-quota';
+/** Snapshot pull cadence in milliseconds. */
+const POLL_INTERVAL_MS = 3000;
+/** Required services: slot registry, connection RPC, locale, settings scope. */
+export const inject = ['slots', 'connection', 'locale', 'settingsScope'];
+/**
+ * Client plugin body: poll the Host snapshot route, run the full-quota
+ * strategy, wire the injected face (directory load, limit write, model
+ * switch, preferences), and register the floating panel into `shell.overlay`.
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'token-quota-ui: panel dictionaries');
+    const t = ctx.locale.bind(NS);
+    const scope = ctx.settingsScope.bind({ namespace: TOKEN_QUOTA_NAMESPACE });
+    const connection = ctx.get('connection');
+    // Store handle shared with the registration; the framework instantiates the
+    // live store per entry and hands its bound actions to the inject factory,
+    // so the apply-world only ever writes through `bound`.
+    const store = createTokenQuotaPanelStore();
+    let bound;
+    let lastGroups = [];
+    let lastCurrent = null;
+    let lastSessionId;
+    let lastMonitored = null;
+    let lastOnFull = 'stop';
+    let lastReset = null;
+    const keyOf = (selection) => {
+        if (selection === null)
+            return undefined;
+        return `${selection.provider}/${selection.model}`;
+    };
+    const isMonitoredKey = (key) => lastMonitored === null || lastMonitored.includes(key);
+    /** Pick an auto-switch target for the configured strategy. */
+    const pickSwitchTarget = (snapshot, currentKey) => {
+        const entryByKey = new Map(snapshot.entries.map(entry => [entry.key, entry]));
+        const candidates = [];
+        for (const group of lastGroups) {
+            for (const model of group.models) {
+                const key = `${group.id}/${model.id}`;
+                if (key === currentKey)
+                    continue;
+                const entry = entryByKey.get(key);
+                candidates.push({
+                    key,
+                    provider: group.id,
+                    model: model.id,
+                    limit: entry?.limit ?? 0,
+                    used: entry?.used ?? 0,
+                });
+            }
+        }
+        const available = (candidate) => isMonitoredKey(candidate.key) && (candidate.limit <= 0 || candidate.used < candidate.limit);
+        if (lastOnFull === 'switchQuota') {
+            return candidates
+                .filter(candidate => isMonitoredKey(candidate.key) && candidate.limit > 0 && candidate.used < candidate.limit)
+                .sort((a, b) => (a.used / a.limit) - (b.used / b.limit))[0];
+        }
+        if (lastOnFull === 'switchAll') {
+            return candidates.filter(available)[0];
+        }
+        // switchPriority: uncapped first, then unmonitored, then capped-but-free.
+        const uncapped = candidates.find(candidate => isMonitoredKey(candidate.key) && candidate.limit <= 0);
+        if (uncapped !== undefined)
+            return uncapped;
+        const unmonitored = candidates.find(candidate => !isMonitoredKey(candidate.key));
+        if (unmonitored !== undefined)
+            return unmonitored;
+        return candidates.find(available);
+    };
+    /** Run the configured full-quota strategy once per exhausted model. */
+    const actOnFull = (snapshot) => {
+        const currentKey = keyOf(lastCurrent);
+        if (currentKey === undefined)
+            return;
+        if (!isMonitoredKey(currentKey))
+            return;
+        const entry = snapshot.entries.find(candidate => candidate.key === currentKey);
+        if (entry === undefined || entry.limit <= 0 || entry.used < entry.limit)
+            return;
+        if (lastOnFull === 'stop' || lastSessionId === undefined) {
+            bound?.setFullNotice(t('fullNotice'));
+            return;
+        }
+        const target = pickSwitchTarget(snapshot, currentKey);
+        if (target === undefined) {
+            bound?.setFullNotice(t('fullSwitchFailed'));
+            return;
+        }
+        void connection.api.sessions.selectModel({
+            sessionId: lastSessionId,
+            provider: target.provider,
+            model: target.model,
+        }).then(({ result }) => {
+            if (result.ok) {
+                lastCurrent = result.value.selected;
+                bound?.setFullNotice(null);
+                pull();
+            }
+            else {
+                bound?.setFullNotice(t('fullSwitchFailed'));
+            }
+        }, () => { bound?.setFullNotice(t('fullSwitchFailed')); });
+    };
+    // Poll the Host's snapshot route and sync panel preferences. The Host is the
+    // single fact source for usage AND the resolved per-model caps; the panel
+    // converges within one poll interval (plus an immediate first pull). Every
+    // few pulls we re-read the model directory so a model switch made OUTSIDE
+    // this panel (the official selector, /model) moves the 「当前」 badge too.
+    let pullCount = 0;
+    const refreshCurrent = () => {
+        if (lastSessionId === undefined)
+            return;
+        void connection.api.sessions.models({ sessionId: lastSessionId }).then(({ result }) => {
+            if (result.ok) {
+                lastGroups = result.value.groups;
+                lastCurrent = result.value.current;
+                bound?.setDirectory(result.value.groups, result.value.current);
+            }
+        }, () => { });
+    };
+    const pull = () => {
+        pullCount += 1;
+        const doc = scope.getSnapshot().value;
+        lastMonitored = doc?.monitored !== undefined && doc.monitored.length > 0 ? doc.monitored : null;
+        lastOnFull = doc?.onFull ?? 'stop';
+        lastReset = doc?.reset !== undefined && doc.reset !== null
+            && typeof doc.reset === 'object'
+            && typeof doc.reset.offsetHours === 'number'
+            ? doc.reset
+            : null;
+        bound?.setSettings(lastMonitored, lastOnFull);
+        bound?.setReset(lastReset);
+        void fetch('/token-quota', { headers: { accept: 'application/json' } }).then((response) => {
+            if (!response.ok) {
+                bound?.setError(`quota route: ${String(response.status)}`);
+                return;
+            }
+            return response.json();
+        }, () => {
+            bound?.setError('quota snapshot pull failed');
+        }).then((snapshot) => {
+            if (snapshot === undefined)
+                return;
+            bound?.setSnapshot(snapshot);
+            actOnFull(snapshot);
+        });
+        if (pullCount % 4 === 0)
+            refreshCurrent();
+    };
+    ctx.effect(() => {
+        pull();
+        const timer = setInterval(pull, POLL_INTERVAL_MS);
+        return () => { clearInterval(timer); };
+    }, 'token-quota-ui: snapshot poll + full strategy');
+    const load = (sessionId) => {
+        lastSessionId = sessionId;
+        bound?.setLoading(true);
+        bound?.setError(null);
+        void connection.api.sessions.models({ sessionId }).then(({ result }) => {
+            if (result.ok) {
+                lastGroups = result.value.groups;
+                lastCurrent = result.value.current;
+                bound?.setDirectory(result.value.groups, result.value.current);
+                bound?.setLoading(false);
+            }
+            else {
+                bound?.setError(`${result.error.code}: ${result.error.message}`);
+                bound?.setLoading(false);
+            }
+        }, () => {
+            bound?.setLoading(false);
+            bound?.setError('directory load failed');
+        });
+    };
+    const setLimit = (key, limit) => {
+        const current = scope.getSnapshot().value?.limits ?? {};
+        void scope.set('limits', { ...current, [key]: limit });
+    };
+    const setMonitored = (monitored) => {
+        lastMonitored = monitored;
+        bound?.setSettings(lastMonitored, lastOnFull);
+        void scope.set('monitored', monitored ?? []);
+    };
+    const setOnFull = (action) => {
+        lastOnFull = action;
+        bound?.setSettings(lastMonitored, lastOnFull);
+        void scope.set('onFull', action);
+    };
+    const setReset = (reset) => {
+        lastReset = reset;
+        bound?.setReset(reset);
+        void scope.set('reset', reset);
+    };
+    const selectModel = (sessionId, provider, model) => {
+        void connection.api.sessions.selectModel({ sessionId, provider, model }).then(({ result }) => {
+            if (result.ok) {
+                lastCurrent = result.value.selected;
+                bound?.setDirectory(lastGroups, result.value.selected);
+                // Immediately re-pull the snapshot so the previous model's final
+                // usage (credited around the switch) shows without waiting 3 s.
+                pull();
+            }
+            else {
+                bound?.setError(`${result.error.code}: ${result.error.message}`);
+            }
+        }, () => {
+            bound?.setError('model switch failed');
+        });
+    };
+    const injected = (actions) => {
+        bound = actions;
+        return { load, setLimit, selectModel, setMonitored, setOnFull, setReset };
+    };
+    ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+        name: 'shell.overlay',
+        id: 'token-quota',
+        order: 100,
+        label: () => t('title'),
+        store,
+        locale: NS,
+        inject: injected,
+    }, TokenQuotaPanel));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Token-quota panel copy (zh + en). The panel is a product surface, so the
+ * primary copy is Chinese with an English pair, mirroring the shipped UI.
+ *
+ * @module @jxgame2020/dsh-token-quota/client/locales
+ */
+/** Simplified Chinese copy (primary). */
+export declare const zh: {
+    title: string;
+    subtitle: string;
+    current: string;
+    unlimited: string;
+    usedToday: string;
+    limitLabel: string;
+    limitPlaceholder: string;
+    save: string;
+    select: string;
+    setLimitHint: string;
+    loading: string;
+    waiting: string;
+    loadError: string;
+    empty: string;
+    collapse: string;
+    expand: string;
+    settings: string;
+    settingsTitle: string;
+    monitorLabel: string;
+    monitorHint: string;
+    monitorAll: string;
+    monitorNone: string;
+    noMonitored: string;
+    fullActionLabel: string;
+    fullStop: string;
+    fullSwitchQuota: string;
+    fullSwitchAll: string;
+    fullSwitchPriority: string;
+    fullNotice: string;
+    fullSwitchFailed: string;
+    close: string;
+    logs: string;
+    logsTitle: string;
+    logEmpty: string;
+    logDay: string;
+    logModel: string;
+    logUsed: string;
+    resetLabel: string;
+    resetHint: string;
+    resetOffset: string;
+    resetTime: string;
+};
+/** Dictionary keys owned by the token-quota panel (a string-literal union). */
+export type TokenQuotaKey = keyof typeof zh;
+/** English copy. */
+export declare const en: {
+    title: string;
+    subtitle: string;
+    current: string;
+    unlimited: string;
+    usedToday: string;
+    limitLabel: string;
+    limitPlaceholder: string;
+    save: string;
+    select: string;
+    setLimitHint: string;
+    loading: string;
+    waiting: string;
+    loadError: string;
+    empty: string;
+    collapse: string;
+    expand: string;
+    settings: string;
+    settingsTitle: string;
+    monitorLabel: string;
+    monitorHint: string;
+    monitorAll: string;
+    monitorNone: string;
+    noMonitored: string;
+    fullActionLabel: string;
+    fullStop: string;
+    fullSwitchQuota: string;
+    fullSwitchAll: string;
+    fullSwitchPriority: string;
+    fullNotice: string;
+    fullSwitchFailed: string;
+    close: string;
+    logs: string;
+    logsTitle: string;
+    logEmpty: string;
+    logDay: string;
+    logModel: string;
+    logUsed: string;
+    resetLabel: string;
+    resetHint: string;
+    resetOffset: string;
+    resetTime: string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/locales.js

@@ -0,0 +1,95 @@
+/**
+ * Token-quota panel copy (zh + en). The panel is a product surface, so the
+ * primary copy is Chinese with an English pair, mirroring the shipped UI.
+ *
+ * @module @jxgame2020/dsh-token-quota/client/locales
+ */
+/** Simplified Chinese copy (primary). */
+export const zh = {
+    title: '每日 Token 限额',
+    subtitle: '按模型实时统计今天的 Token 消耗',
+    current: '当前',
+    unlimited: '不限',
+    usedToday: '今日已用',
+    limitLabel: '上限',
+    limitPlaceholder: '填数字，0=不限',
+    save: '保存',
+    select: '选择',
+    setLimitHint: '设置限额',
+    loading: '加载中…',
+    waiting: '等待数据…',
+    loadError: '加载失败',
+    empty: '暂无模型数据',
+    collapse: '收起',
+    expand: '展开',
+    settings: '设置',
+    settingsTitle: '限额设置',
+    monitorLabel: '监控模型',
+    monitorHint: '未勾选的模型不显示、不计入用量、不受限额限制',
+    monitorAll: '全部',
+    monitorNone: '无',
+    noMonitored: '未监控任何模型',
+    fullActionLabel: '满额后处理',
+    fullStop: '停止请求并提示',
+    fullSwitchQuota: '自动切换到其它限额模型',
+    fullSwitchAll: '自动切换到其它可用模型（含非限额）',
+    fullSwitchPriority: '自动切换（优先非限额，其次未监控）',
+    fullNotice: '当前模型今日额度已用尽，请求已停止。请选择其它模型或调整限额。',
+    fullSwitchFailed: '没有可切换的模型（所有限额模型均已满额）',
+    close: '关闭',
+    logs: '日志',
+    logsTitle: '用量日志',
+    logEmpty: '暂无记录',
+    logDay: '日期',
+    logModel: '模型',
+    logUsed: '用量',
+    resetLabel: '每日重置时间',
+    resetHint: '选择时区与时间，到点自动清零当日计数',
+    resetOffset: '时区',
+    resetTime: '时间',
+};
+/** English copy. */
+export const en = {
+    title: 'Daily Token Quota',
+    subtitle: 'Real-time per-model token usage today',
+    current: 'current',
+    unlimited: 'unlimited',
+    usedToday: 'used today',
+    limitLabel: 'limit',
+    limitPlaceholder: 'number, 0 = unlimited',
+    save: 'Save',
+    select: 'Select',
+    setLimitHint: 'Set limit',
+    loading: 'Loading…',
+    waiting: 'Waiting…',
+    loadError: 'Load failed',
+    empty: 'No model data',
+    collapse: 'Collapse',
+    expand: 'Expand',
+    settings: 'Settings',
+    settingsTitle: 'Quota Settings',
+    monitorLabel: 'Monitored models',
+    monitorHint: 'Unchecked models are hidden, not metered, and never capped',
+    monitorAll: 'All',
+    monitorNone: 'None',
+    noMonitored: 'No model monitored',
+    fullActionLabel: 'When a model is full',
+    fullStop: 'Stop and prompt',
+    fullSwitchQuota: 'Switch to another quota model',
+    fullSwitchAll: 'Switch to any other model (incl. uncapped)',
+    fullSwitchPriority: 'Prefer uncapped, then unmonitored',
+    fullNotice: 'Today\u2019s quota for the current model is exhausted; the request was stopped. Pick another model or raise its limit.',
+    fullSwitchFailed: 'No switchable model (all quota models are full)',
+    close: 'Close',
+    logs: 'Logs',
+    logsTitle: 'Usage Log',
+    logEmpty: 'No records',
+    logDay: 'Day',
+    logModel: 'Model',
+    logUsed: 'Used',
+    resetLabel: 'Daily reset',
+    resetHint: 'Pick a timezone and time; counters reset there',
+    resetOffset: 'Timezone',
+    resetTime: 'Time',
+};
+//# sourceMappingURL=locales.js.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Token-quota panel store: the shared, remount-surviving view state. The
+ * apply-world is the only writer — forwarded `token-quota/updated` snapshots
+ * and the model-directory loader feed it — while the panel reads through
+ * `useStore`. Display rows are derived data (pure function over the two
+ * sources), so the component builds them with `useMemo`, never a store scan.
+ *
+ * @module @deepseek-ai/dsh-client-ui-token-quota/client/store
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ModelProviderGroup, ModelSelection } from '@deepseek-ai/dsh-api-remotes/client';
+import type { TokenQuotaFullAction, TokenQuotaLog, TokenQuotaReset, TokenQuotaSnapshot } from '@jxgame2020/dsh-token-quota/types';
+/** One rendered model row: directory identity merged with the quota snapshot. */
+export interface ModelQuotaRow {
+    /** Stable key `provider/model`. */
+    key: string;
+    /** Registered provider route. */
+    provider: string;
+    /** Provider-owned model id. */
+    model: string;
+    /** Display name from the directory, falling back to the model id. */
+    name: string;
+    /** Tokens used today (input + output + cache). */
+    used: number;
+    /** Daily cap; `0` means unlimited. */
+    limit: number;
+    /** Whether the current session uses this route. */
+    current: boolean;
+}
+/** Panel view state. */
+export interface TokenQuotaPanelState {
+    /** Latest quota snapshot from the Host; null before the first event lands. */
+    snapshot: TokenQuotaSnapshot | null;
+    /** Advisory model directory of the current session (provider groups). */
+    groups: readonly ModelProviderGroup[];
+    /** Current model selection reported by the Host. */
+    current: ModelSelection | null;
+    /** Directory load in flight. */
+    loading: boolean;
+    /** Last load/selection failure text; null when none. */
+    error: string | null;
+    /**
+     * Model keys under active monitoring; `null` means every model (default).
+     * Unmonitored models are hidden, not metered, and never capped.
+     */
+    monitored: string[] | null;
+    /** Behavior when a monitored, capped model reaches its daily cap. */
+    onFull: TokenQuotaFullAction;
+    /** Whether the settings dialog is open. */
+    dialogOpen: boolean;
+    /** Full-quota notice shown for the `'stop'` strategy; null when none. */
+    fullNotice: string | null;
+    /** Daily reset moment; `null` = machine-local midnight. */
+    reset: TokenQuotaReset | null;
+    /** Whether the usage-log dialog is open. */
+    logOpen: boolean;
+    /** Latest usage history; null before the first fetch. */
+    log: TokenQuotaLog | null;
+}
+/** Declared write surface. */
+export type TokenQuotaPanelActions = {
+    setSnapshot: (d: TokenQuotaPanelState, snapshot: TokenQuotaSnapshot) => void;
+    setDirectory: (d: TokenQuotaPanelState, groups: readonly ModelProviderGroup[], current: ModelSelection | null) => void;
+    setLoading: (d: TokenQuotaPanelState, loading: boolean) => void;
+    setError: (d: TokenQuotaPanelState, error: string | null) => void;
+    setSettings: (d: TokenQuotaPanelState, monitored: string[] | null, onFull: TokenQuotaFullAction) => void;
+    setDialogOpen: (d: TokenQuotaPanelState, open: boolean) => void;
+    setFullNotice: (d: TokenQuotaPanelState, notice: string | null) => void;
+    setReset: (d: TokenQuotaPanelState, reset: TokenQuotaReset | null) => void;
+    setLogOpen: (d: TokenQuotaPanelState, open: boolean) => void;
+    setLog: (d: TokenQuotaPanelState, log: TokenQuotaLog | null) => void;
+};
+/**
+ * Declares the panel state and write surface.
+ * @returns the store handle.
+ */
+export declare function createTokenQuotaPanelStore(): EngineStoreHandle<TokenQuotaPanelState, TokenQuotaPanelActions>;
+/**
+ * Merge the session's model directory with the quota snapshot into display
+ * rows. Every directory model gets a row (usage/limit fall back to
+ * `0`/`0`), and snapshot entries for routes missing from the directory are
+ * appended so no counter is ever hidden.
+ * @param groups - advisory provider groups of the current session.
+ * @param snapshot - latest quota snapshot, or null before the first one.
+ * @param current - current model selection reported by the Host.
+ * @returns rows sorted by key.
+ */
+export declare function mergeModelRows(groups: readonly ModelProviderGroup[], snapshot: TokenQuotaSnapshot | null, current: ModelSelection | null): ModelQuotaRow[];
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/store.js

@@ -0,0 +1,92 @@
+/**
+ * Token-quota panel store: the shared, remount-surviving view state. The
+ * apply-world is the only writer — forwarded `token-quota/updated` snapshots
+ * and the model-directory loader feed it — while the panel reads through
+ * `useStore`. Display rows are derived data (pure function over the two
+ * sources), so the component builds them with `useMemo`, never a store scan.
+ *
+ * @module @deepseek-ai/dsh-client-ui-token-quota/client/store
+ */
+import { defineStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** Build the stable per-model key shared by the counter, settings, and snapshot. */
+function tokenQuotaKey(provider, model) {
+    return `${provider}/${model}`;
+}
+/**
+ * Declares the panel state and write surface.
+ * @returns the store handle.
+ */
+export function createTokenQuotaPanelStore() {
+    return defineStore({
+        init: () => ({
+            snapshot: null,
+            groups: [],
+            current: null,
+            loading: false,
+            error: null,
+            monitored: null,
+            onFull: 'stop',
+            dialogOpen: false,
+            fullNotice: null,
+            reset: null,
+            logOpen: false,
+            log: null,
+        }),
+        actions: {
+            setSnapshot: (d, snapshot) => { d.snapshot = snapshot; },
+            setDirectory: (d, groups, current) => { d.groups = groups; d.current = current; },
+            setLoading: (d, loading) => { d.loading = loading; },
+            setError: (d, error) => { d.error = error; },
+            setSettings: (d, monitored, onFull) => { d.monitored = monitored; d.onFull = onFull; },
+            setDialogOpen: (d, open) => { d.dialogOpen = open; },
+            setFullNotice: (d, notice) => { d.fullNotice = notice; },
+            setReset: (d, reset) => { d.reset = reset; },
+            setLogOpen: (d, open) => { d.logOpen = open; },
+            setLog: (d, log) => { d.log = log; },
+        },
+    });
+}
+/**
+ * Merge the session's model directory with the quota snapshot into display
+ * rows. Every directory model gets a row (usage/limit fall back to
+ * `0`/`0`), and snapshot entries for routes missing from the directory are
+ * appended so no counter is ever hidden.
+ * @param groups - advisory provider groups of the current session.
+ * @param snapshot - latest quota snapshot, or null before the first one.
+ * @param current - current model selection reported by the Host.
+ * @returns rows sorted by key.
+ */
+export function mergeModelRows(groups, snapshot, current) {
+    const entryByKey = new Map((snapshot?.entries ?? []).map(entry => [entry.key, entry]));
+    const rows = new Map();
+    for (const group of groups) {
+        for (const model of group.models) {
+            const key = tokenQuotaKey(group.id, model.id);
+            const entry = entryByKey.get(key);
+            rows.set(key, {
+                key,
+                provider: group.id,
+                model: model.id,
+                name: model.name,
+                used: entry?.used ?? 0,
+                limit: entry?.limit ?? 0,
+                current: current !== null && current.provider === group.id && current.model === model.id,
+            });
+        }
+    }
+    for (const entry of snapshot?.entries ?? []) {
+        if (rows.has(entry.key))
+            continue;
+        rows.set(entry.key, {
+            key: entry.key,
+            provider: entry.provider,
+            model: entry.model,
+            name: entry.model,
+            used: entry.used,
+            limit: entry.limit,
+            current: current !== null && current.provider === entry.provider && current.model === entry.model,
+        });
+    }
+    return [...rows.values()].sort((left, right) => left.key.localeCompare(right.key));
+}
+//# sourceMappingURL=store.js.map