@cassius0924/dsh-usage-dashboard 0.8.0 → 0.8.3

package/lib/types/breaker-gate.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The peak-window breaker gate.
+ *
+ * DeepSeek's `agent/pre-step` is a waterfall: a listener receives the proposed
+ * step and either calls `next()` (let it proceed) or withholds it (park). This
+ * gate parks steps only when all conditions hold:
+ *
+ * - the master switch is on,
+ * - the step's agent (its session) opted in via its own switch,
+ * - a peak window is open,
+ * - the turn was started by a person (`source.kind === 'user'`).
+ *
+ * Parked steps resume when the window settles at 18:00, when the user lets them
+ * continue from the UI, or when the owning turn is cancelled (`signal` aborts —
+ * abort must let the loop unwind normally instead of throwing here).
+ *
+ * Steps after the first one in a turn can carry no messages, so the "was this a
+ * user turn" decision is remembered per `(session, turn)`. The same memory
+ * records a manual release so the user's "continue now" is not undone by the
+ * very next step of that turn. Both are bounded: sessions come and go, but the
+ * map must not grow forever on a long-lived host.
+ *
+ * Timer handling is split behind `BreakerTimerFace` so tests can drive a fake
+ * clock; the production face uses a real `setTimeout`, unrefs it (a parked turn
+ * must never keep the process alive) and re-arms long waits in chunks, because
+ * `setTimeout` cannot represent delays above `MAX_BREAKER_TIMER_DELAY_MS`.
+ */
+import { type BreakerSettings } from './contract.ts';
+import { type BreakerMessageFace } from './breaker.ts';
+/** The timer seam; production uses `systemBreakerTimers`, tests a fake clock. */
+export interface BreakerTimerFace {
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+/** `setTimeout`'s documented maximum delay; longer waits are re-armed. */
+export declare const MAX_BREAKER_TIMER_DELAY_MS = 2147483647;
+/** Production timers: a real unref'd `setTimeout`. */
+export declare const systemBreakerTimers: BreakerTimerFace;
+/** Clamp one wait into the range a single `setTimeout` can carry. */
+export declare const clampBreakerTimerDelay: (delayMs: number) => number;
+export interface BreakerGateOptions {
+    /** Settings to start from; the host loads persisted ones asynchronously. */
+    initialSettings?: BreakerSettings;
+    /** Clock seam, epoch ms; defaults to `Date.now`. */
+    now?: () => number;
+    /** Timer seam; defaults to the real clock. */
+    timers?: BreakerTimerFace;
+}
+export declare class BreakerGate {
+    #private;
+    constructor(options?: BreakerGateOptions);
+    get settings(): BreakerSettings;
+    /** Steps parked right now, across every session. */
+    get held(): number;
+    /** Session ids with at least one parked step, sorted for the wire projection. */
+    get heldSessions(): string[];
+    /**
+     * Park one proposed step until it may proceed. Resolves immediately when the
+     * step is not subject to the breaker (session not opted in, off-peak,
+     * machine-started turn, turn already released by hand) or when the turn is
+     * aborted/disposed.
+     *
+     * The listener wrapping this must call `next()` after it resolves — this
+     * method never throws and never returns a decision of its own.
+     *
+     * `sessionId` is the agent id from the payload; an agent without one cannot
+     * be matched against the opt-in list, so its steps pass.
+     */
+    hold(sessionId: string | undefined, turn: number, messages: readonly BreakerMessageFace[], signal: AbortSignal): Promise<void>;
+    /**
+     * Let parked steps continue now. `sessionId` narrows it to one session; no
+     * argument releases every parked step (the UI's "continue all" button). The
+     * released turns are remembered, because re-parking their next step would
+     * contradict the user's instruction.
+     * @returns how many parked steps were released.
+     */
+    release(sessionId?: string): number;
+    /**
+     * Apply new settings. Turning off the master switch — or a session's own
+     * switch — releases the affected parked steps immediately and without
+     * remembering a bypass: that is the user's decision, not a request for one
+     * particular turn to run.
+     */
+    update(settings: BreakerSettings): void;
+    /** Release everything and stop the timer; called when the plugin unloads. */
+    dispose(): void;
+    /** (Re)arm the single settle timer for the current peak window. */
+    private armTimer;
+    private onTimer;
+    private clearTimer;
+    private releaseRecord;
+    private markReleased;
+    private rememberTurn;
+}

package/lib/types/breaker-settings.d.ts

@@ -0,0 +1,28 @@
+import { type BreakerSettings } from './contract.ts';
+/**
+ * Resolve the settings file path from the environment. The env parameter is
+ * injectable so tests can exercise the `DSH_HOME` branch without touching the
+ * process environment.
+ * @param env - environment to read `DSH_HOME` from; defaults to `process.env`.
+ */
+export declare function breakerSettingsPath(env?: NodeJS.ProcessEnv): string;
+/** Shared IO options; the defaults are what the running plugin uses. */
+export interface BreakerSettingsIoOptions {
+    /** Explicit file path, bypassing {@link breakerSettingsPath}. */
+    filePath?: string;
+    /** Warning sink, so tests can capture instead of printing. */
+    warn?: (message: string) => void;
+}
+/**
+ * Read persisted settings. A missing file is the first-run case and returns
+ * the defaults silently; unreadable, malformed, or structurally invalid
+ * content warns and returns the defaults.
+ */
+export declare function loadBreakerSettings(options?: BreakerSettingsIoOptions): Promise<BreakerSettings>;
+/**
+ * Persist settings atomically. The temp file is created beside the target and
+ * renamed over it, so readers only ever see a complete document.
+ * @param settings - master switch and session opt-ins; normalized before writing.
+ * @param options - explicit path, if any.
+ */
+export declare function saveBreakerSettings(settings: BreakerSettings, options?: Pick<BreakerSettingsIoOptions, 'filePath'>): Promise<void>;

package/lib/types/breaker.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Peak-window breaker decisions — pure functions, no timers or IO.
+ *
+ * DeepSeek charges peak rates in Beijing time 09:00–12:00 and 14:00–18:00 on
+ * weekdays (see `pricing.ts`, which owns that definition). A session that opted
+ * in parks its user-started steps while a peak window is open and lets them
+ * continue at 18:00 — the end of the day's last peak window — so one pause
+ * covers both windows without a lunch-time exception.
+ *
+ * All time math is done in Beijing time (UTC+8) rather than the machine's local
+ * zone, matching the price table.
+ */
+import { type BreakerData, type BreakerSettings } from './contract.ts';
+/** Peak windows in Beijing time, display-only copy shared with `pricingInfo`. */
+export declare const BREAKER_PEAK_WINDOWS: readonly ["09:00–12:00", "14:00–18:00"];
+/**
+ * The one field of a message this module inspects: its producer. Only
+ * `kind === 'user'` means a person started the turn in a chat; scheduled
+ * tasks, goal continuations and subagent relays all carry another kind and are
+ * therefore never parked.
+ */
+export interface BreakerMessageFace {
+    source?: {
+        kind?: string;
+    };
+}
+/**
+ * When the current peak window settles: 18:00 Beijing time on the same day.
+ * Outside peak there is nothing to wait for, so the answer is `now`.
+ *
+ * A peak window can only be open between 09:00 and 18:00 on a weekday, so the
+ * same-day 18:00 instant is always in the future here. Converting through
+ * UTC+8 schedules the same instant on a host in another timezone.
+ */
+export declare function nextResumeAt(nowMs: number): number;
+/**
+ * Whether these proposed-step messages belong to a turn a person started. A
+ * single user-produced message is enough: a step that carries it is part of
+ * the user's request, whatever else the batch holds.
+ */
+export declare function isUserTurn(messages: readonly BreakerMessageFace[]): boolean;
+/**
+ * A copy holding exactly the contract fields, with session ids deduplicated,
+ * filtered to the charset sessions can actually have, and sorted so persisted
+ * documents and API projections are stable.
+ */
+export declare function normalizeBreakerSettings(settings: BreakerSettings): BreakerSettings;
+/** Project live gate state into the wire shape the client renders. */
+export declare function breakerProject(settings: BreakerSettings, nowMs: number, holding: readonly string[]): BreakerData;

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

@@ -1,4 +1,4 @@
-import type { BalanceResponse, SessionUsageResponse, UsageResponse } from '../contract.ts';
+import type { BalanceResponse, BreakerReleaseRequest, BreakerResponse, BreakerSettingsRequest, SessionUsageResponse, UsageResponse } from '../contract.ts';
 /** Last cached value (possibly stale), for an instant first render. */
 export declare const getCachedBalance: () => BalanceResponse | null;
 export declare const getCachedUsage: () => UsageResponse | null;
@@ -10,3 +10,10 @@ export declare function fetchUsage(force?: boolean): Promise<UsageResponse>;
 export declare const getCachedSessionUsage: (sessionId: string) => SessionUsageResponse | null;
 export declare const subscribeSessionUsage: (sessionId: string, fn: () => void) => (() => void);
 export declare function fetchSessionUsage(sessionId: string, force?: boolean): Promise<SessionUsageResponse>;
+/** Current projection: opted-in sessions plus the live peak/holding status. */
+export declare function fetchBreaker(): Promise<BreakerResponse>;
+/** Write one switch: `sessionId` targets that conversation, omitting it targets
+ *  the master switch. The host answers with the full projection. */
+export declare function updateBreaker(request: BreakerSettingsRequest): Promise<BreakerResponse>;
+/** Let parked work continue now; an omitted target means every parked session. */
+export declare function releaseBreaker(request?: BreakerReleaseRequest): Promise<BreakerResponse>;

package/lib/types/client/breaker-pill.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 高峰暂停 pill in the composer dock, beside the host's own
+ * 「会话统计」/「Token 用量」pills and this plugin's 「会话费用」pill. It is the
+ * switch for the current conversation only: on means this session's
+ * user-started turns pause during Beijing-time peak pricing and resume at
+ * 18:00. The 额度 page lists every session that opted in and carries the
+ * master switch; this pill is where a single conversation opts in.
+ *
+ * The three states are told apart by three channels at once, never colour
+ * alone: copy (「高峰暂停 · 关」/「高峰暂停 · 开」/「已暂停 · 18:00」), glyph
+ * (outline / solid) and colour (neutral / primary / warn).
+ *
+ * Skin and geometry mirror `./session-cost-pill.tsx` (same slot, same
+ * `.dq-cost-pill`), so the dock reads as one row. The switch writes
+ * optimistically, then takes the host's returned projection as truth; a
+ * failure rolls back and is surfaced through `title`/`aria-label` only.
+ */
+import { type ReactElement } from 'react';
+export declare function BreakerPill({ sessionId }: {
+    sessionId?: string;
+}): ReactElement | null;

package/lib/types/client/breaker-state.d.ts

@@ -0,0 +1,8 @@
+import type { BreakerData } from '../contract.ts';
+/** Latest host projection, or null before the first read lands. */
+export declare function getBreakerData(): BreakerData | null;
+/** Replace the projection and notify both surfaces. */
+export declare function publishBreakerData(data: BreakerData | null): void;
+export declare function subscribeBreakerData(listener: () => void): () => void;
+/** Subscribe the calling component to the shared projection. */
+export declare function useBreakerData(): BreakerData | null;

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

@@ -0,0 +1,60 @@
+/**
+ * Client-side helpers for the session-scoped peak breaker: response-shape
+ * validation (the host half may not be restarted yet, so an absent or
+ * malformed payload must degrade to「状态暂不可用」instead of crashing),
+ * per-session projections for optimistic switches, and pure display
+ * formatting that is independent of the browser timezone.
+ */
+import { type BreakerData, type BreakerResponse } from '../contract.ts';
+/**
+ * Narrow a response to one whose every field the UI dereferences exists.
+ * Mirrors `usageIsUsable` in ./api.ts: a stale host that does not serve the
+ * breaker route (404) or an older payload shape falls through to the neutral
+ * copy rather than being rendered as if it were current.
+ */
+export declare function breakerIsUsable(res: BreakerResponse | null | undefined): res is BreakerResponse & {
+    data: BreakerData;
+};
+/**
+ * `HH:mm` in Beijing time for an ISO instant, or null when absent/unparseable.
+ *
+ * Computed through the fixed +08:00 offset rather than `Intl`/local Date
+ * getters: the resume clock is defined in Beijing time, and the browser may be
+ * in any timezone (same approach as ./budget.ts's month boundary).
+ */
+export declare function beijingClock(iso: string | null | undefined): string | null;
+/** Whether `sessionId` itself opted in, ignoring the master switch. */
+export declare function isSessionOptedIn(data: BreakerData | null, sessionId: string | null | undefined): boolean;
+/** Whether `sessionId`'s opt-in is in force: its own switch and the master switch. */
+export declare function isSessionEnabled(data: BreakerData | null, sessionId: string | null | undefined): boolean;
+/** Switch a session's breaker can be in; `holding` means it is parked right now. */
+export type SessionBreakerState = 'off' | 'on' | 'holding';
+/**
+ * Per-session state for the composer pill. Holding is only reported for an
+ * enabled session: a release can race a stale projection, and a session the
+ * host no longer lists must read as off regardless of the holding list. With
+ * the master switch off nothing is in force, so the pill reads off too.
+ */
+export declare function sessionBreakerState(data: BreakerData | null, sessionId: string | null | undefined): SessionBreakerState;
+/**
+ * Projection with one session switched on/off, used for the optimistic state
+ * before the host answers. Disabling also drops the session from `holding`:
+ * off means nothing is parked for it.
+ */
+export declare function withSessionToggled(data: BreakerData | null, sessionId: string, enabled: boolean): BreakerData | null;
+/**
+ * Projection with the master switch flipped, used for the optimistic state
+ * before the host answers. Off means nothing is parked — per-session switches
+ * are kept, so the 额度 page can still list and manage them.
+ */
+export declare function withMasterToggled(data: BreakerData | null, enabled: boolean): BreakerData | null;
+/** Title fallback for a session whose title has not been read yet. */
+export declare function shortSessionId(sessionId: string): string;
+/**
+ * Which status row the 额度 page's breaker card shows. `unavailable` means the
+ * host route could not be read (or answered with a shape this client cannot
+ * use); `masterOff` outranks the peak phases because nothing pauses then. The
+ * peak phases depend only on the host clock and holding list.
+ */
+export type BreakerPhase = 'unavailable' | 'masterOff' | 'offPeak' | 'peak' | 'peakHolding';
+export declare function breakerPhase(data: BreakerData | null): BreakerPhase;

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

@@ -58,4 +58,12 @@ export declare function Heatmap(props: {
 }): ReactElement;
 export declare const fmt: (v: string | number) => string;
 export declare const fmtInt: (v: number | undefined) => string;
+/**
+ * Compact token/count formatting. English delegates to `Intl` compact notation;
+ * Simplified Chinese keeps the 万/亿 scale words because "1.6万 tokens" reads
+ * faster than "16K tokens" to Chinese readers.
+ * @param v - raw number of tokens or calls.
+ * @param locale - active plugin locale; defaults to Simplified Chinese.
+ * @returns the compact string.
+ */
 export declare const fmtCompact: (v: number | undefined, locale?: LocaleId) => string;

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

@@ -1,12 +1,33 @@
 import { type ReactElement, type ReactNode } from 'react';
 import { type LocaleKey } from './locales.ts';
+/**
+ * Locales this plugin ships copy for: DSH's two built-in locales — Simplified
+ * Chinese (`zh`, the host's own id) and English (`en`). The plugin keeps the
+ * host's language catalog untouched on purpose: language selection stays a DSH
+ * setting, and contributing a plugin-private third language would leave the
+ * host UI and this dashboard speaking different languages, because no other
+ * package ships a dictionary for it.
+ */
 export type LocaleId = 'zh' | 'en';
+/**
+ * Resolve the `Intl` tag for a plugin locale.
+ * @param locale - active plugin locale.
+ * @returns the BCP 47 tag to pass to `Intl.*` / `toLocaleString`.
+ */
+export declare function intlLocale(locale: LocaleId): string;
 export type Translate = (key: LocaleKey, params?: Record<string, unknown>) => string;
 export declare const fallbackT: Translate;
 export declare function LocaleProvider(props: {
     t: Translate;
     children: ReactNode;
 }): ReactElement;
+/**
+ * Read the translate function plus the concrete locale it is bound to. The
+ * identity rides the dictionary itself (`meta.locale`), because slot components
+ * receive only the `t` seat, not the host's locale snapshot; every dictionary
+ * stores its own id there, so a language switch moves both together.
+ * @returns the active `t` and the plugin locale it resolves to.
+ */
 export declare function useI18n(): {
     t: Translate;
     locale: LocaleId;

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

@@ -189,6 +189,7 @@ export declare const zh: {
     readonly 'balance.granted': "赠送额度 {amount}";
     readonly 'balance.runway': "预计可用";
     readonly 'balance.runwayBreakdownTitle': "查看预计可用天数说明";
+    readonly 'balance.topUpTitle': "余额偏低，前往 DeepSeek 开放平台充值（新标签页打开）";
     readonly 'balance.days': "{count} 天";
     readonly 'balance.overYear': "> 365 天";
     readonly 'balance.noRunway': "近 {days} 天没有用量，无法估算";
@@ -227,6 +228,9 @@ export declare const zh: {
     readonly 'settings.widgetTabs': "展示浮窗的页面";
     readonly 'settings.widgetTabsHint': "列表会随已安装的页面自动更新。";
     readonly 'settings.widgetTabsEmpty': "当前没有可配置的会话页面。";
+    readonly 'settings.peakPause': "高峰暂停";
+    readonly 'settings.peakPauseHint': "总开关；关闭后所有会话都不暂停。每个会话的开关会保留，可随时重新打开。";
+    readonly 'settings.peakPauseLoading': "正在读取总开关状态…";
     readonly 'settings.lowBalance': "余额预警线";
     readonly 'settings.lowBalanceOn': "余额低于 {amount} {currency} 时，这里和悬浮窗都会转为警示色。填 0 关闭。";
     readonly 'settings.lowBalanceOff': "已关闭余额预警。填一个大于 0 的数开启。";
@@ -243,6 +247,32 @@ export declare const zh: {
     readonly 'settings.tabDragAria': "拖动「额度」调整标签位置";
     readonly 'settings.tabMoveEarlier': "前移";
     readonly 'settings.tabMoveLater': "后移";
+    readonly 'breaker.title': "高峰暂停";
+    readonly 'breaker.desc': "在对话输入框旁按会话开启；高峰时段自动暂停该会话，18:00 继续。自动化任务不受影响；总开关在「设置」卡里。";
+    readonly 'breaker.pillOff': "高峰暂停 · 关";
+    readonly 'breaker.pillOn': "高峰暂停 · 开";
+    readonly 'breaker.pillHolding': "已暂停 · {clock}";
+    readonly 'breaker.pillAriaOff': "高峰暂停：本会话关闭，点击开启";
+    readonly 'breaker.pillAriaOn': "高峰暂停：本会话开启，{clock} 继续，点击关闭";
+    readonly 'breaker.pillAriaHolding': "高峰暂停：本会话正在暂停，{clock} 继续，点击关闭";
+    readonly 'breaker.pillAriaMasterOff': "高峰暂停：总开关已关闭，本会话不会暂停；点击只切换本会话开关";
+    readonly 'breaker.pillTitleOff': "高峰时段暂停本会话：当前关闭，点击开启";
+    readonly 'breaker.pillTitleOn': "高峰时段暂停本会话：当前开启，{clock} 继续；点击关闭";
+    readonly 'breaker.pillTitleHolding': "本会话正在暂停，{clock} 继续；点击关闭";
+    readonly 'breaker.pillTitleMasterOff': "高峰暂停的总开关已在额度页关闭，本会话不会暂停；点击只切换本会话开关";
+    readonly 'breaker.actionError': "操作失败：{error}";
+    readonly 'breaker.loading': "载入中…";
+    readonly 'breaker.statusUnavailable': "状态暂不可用";
+    readonly 'breaker.statusMasterOff': "总开关已关闭，所有会话都不暂停；可在「设置」卡重新打开";
+    readonly 'breaker.statusOffPeak': "闲时 · 不暂停会话";
+    readonly 'breaker.statusPeak': "高峰时段 · 开启的会话会自动暂停";
+    readonly 'breaker.statusHolding': "已暂停 {count} 个会话 · {clock} 继续";
+    readonly 'breaker.statusHoldingNoClock': "已暂停 {count} 个会话";
+    readonly 'breaker.release': "立即全部继续";
+    readonly 'breaker.releaseBusy': "正在继续…";
+    readonly 'breaker.empty': "还没有会话开启高峰暂停。在对话输入框旁的「高峰暂停」开关里开启。";
+    readonly 'breaker.rowDisableAria': "关闭「{title}」的高峰暂停";
+    readonly 'breaker.holding': "暂停中 · {clock}";
     readonly 'panel.caption': "账户级 · 跨全部会话";
     readonly 'panel.openAria': "打开额度页";
     readonly 'widget.updatedNow': "刚刚更新";
@@ -262,6 +292,9 @@ export declare const zh: {
     readonly 'widget.expandAria': "展开额度窗口";
     readonly 'widget.collapseAria': "收起额度窗口";
     readonly 'messageCost.label': "本轮费用";
+    readonly 'sessionCost.title': "会话费用";
+    readonly 'sessionCost.aria': "本会话估算费用 {amount}";
+    readonly 'sessionCost.active': "活跃时间";
     readonly 'messageCost.tooltip': "由 dsh-usage-dashboard 提供 · 本轮对话费用为估算值";
     readonly 'messageCost.aria': "{amount}，本轮对话估算费用，由 dsh-usage-dashboard 提供";
     readonly 'boundary.title': "额度面板出错了";

package/lib/types/client/session-cost-pill.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Session cost pill in the composer dock (next to the host's「会话统计」and
+ * 「Token 用量」pills). It shows the estimated spend of the whole conversation
+ * and opens a small detail dialog above the dock — the same pill/dialog skin
+ * the host uses for its own composer statistics, so the three read as one row.
+ *
+ * The figure comes from the plugin's own session-usage API (the same endpoint
+ * the 「额度」tab's current-session card and the per-turn chip use), not from
+ * host projections: cost has to follow this plugin's pricing table.
+ */
+import { type ReactElement } from 'react';
+/** One session cost reading plus its click-open breakdown. */
+export declare function SessionCostPill({ sessionId }: {
+    sessionId?: string;
+}): ReactElement | null;