@cassius0924/dsh-usage-dashboard 0.8.3 → 0.9.0

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

@@ -1,94 +0,0 @@
-/**
- * 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

@@ -1,28 +0,0 @@
-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

@@ -1,49 +0,0 @@
-/**
- * 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/breaker-pill.d.ts

@@ -1,21 +0,0 @@
-/**
- * 高峰暂停 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

@@ -1,8 +0,0 @@
-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

@@ -1,60 +0,0 @@
-/**
- * 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;