@jxgame2020/dsh-token-quota 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Daily per-model token quota enforcement and accounting for the harness.
+ *
+ * The service owns three responsibilities, all driven by the existing agent
+ * and session extension points — no loop modification:
+ *
+ * 1. **Accounting** — folds each live session's `request/header` to learn the
+ *    `provider/model` in use, and credits the combined input + output + cache
+ *    token count of every `assistant/message` that reports provider usage into
+ *    that model's current-UTC-day bucket. Counters persist to a JSON file
+ *    under the Harness home and roll over automatically at UTC midnight.
+ *
+ * 2. **Enforcement** — on the `agent/request` waterfall it awaits the resolved
+ *    call config, and when the selected model's daily usage is at or above its
+ *    configured cap (a positive limit), it throws an {@link LlmError} with
+ *    `TOKEN_QUOTA_EXCEEDED`, ending the turn before any provider request is
+ *    dispatched. A limit of `0` (or no entry) leaves the model unlimited.
+ *
+ * 3. **Limits + pull** — per-model limits live in the settings document
+ *    (`token-quota` namespace, written by the Web panel through the settings
+ *    scope); every change re-reads them. The current snapshot is served to
+ *    consumers over a plugin-owned HTTP route (`GET /token-quota`, registered
+ *    on the existing `webServer` service when one exists); the browser panel
+ *    polls it, so no core-Harness wiring or generated RPC contract is needed.
+ *
+ * The browser half (`src/client/`) renders a floating panel from the polled
+ * snapshot and writes limits back through the settings scope; this module
+ * stays browser-free (the optional route is plain node:http).
+ *
+ * @module @jxgame2020/dsh-token-quota
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import '@deepseek-ai/dsh-agent';
+import { type TokenQuotaConfig, type TokenQuotaLog, type TokenQuotaSnapshot } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The token-quota service (`@jxgame2020/dsh-token-quota`). */
+        tokenQuota: TokenQuotaService;
+    }
+}
+/**
+ * Daily token-quota service.
+ *
+ * Mount it beside the other rows (`@jxgame2020/dsh-token-quota`) and write
+ * per-model limits through the `token-quota` settings namespace.
+ */
+export declare class TokenQuotaService extends Service {
+    static Config: z<TokenQuotaConfig>;
+    private readonly storagePath;
+    private reset;
+    private cycle;
+    private usage;
+    private history;
+    private limits;
+    private monitored;
+    private settingsSource;
+    /** Per-session folded model key from the latest `request/header`. */
+    private readonly headerKeys;
+    private writeTimer;
+    /** Disposer for the optional HTTP snapshot route (`GET /token-quota`). */
+    private disposeRoute;
+    /** Disposer for the optional usage-history route (`GET /token-quota/log`). */
+    private disposeRouteLog;
+    /** Disposer for the webServer-arrival watcher when the service mounts later. */
+    private disposeRouteWatcher;
+    /**
+     * @param ctx - owning context (events and the settings section register on it).
+     * @param config - optional counter path.
+     */
+    constructor(ctx: Context, config?: TokenQuotaConfig);
+    /** Serve the current snapshot over the plugin-owned HTTP route. */
+    private tryMountRoute;
+    /** Read the full per-cycle usage history (log dialog data). */
+    readLog(): TokenQuotaLog;
+    /** Read the current snapshot (also used by tests and inspection). */
+    readSnapshot(): TokenQuotaSnapshot;
+    /** Today's used tokens for one model key, or `0`. */
+    usedToday(key: string): number;
+    /** Whether a model is under active monitoring (undefined = every model). */
+    isMonitored(key: string): boolean;
+    /** Resolve one model's daily cap: positive = capped, `0` = unlimited. */
+    limitOf(key: string): number;
+    private onSessionEvent;
+    private onRequest;
+    /**
+     * Roll over to a new reset cycle, archiving the finished cycle's counters
+     * into the history log, when the cycle key changed.
+     * @returns whether a rollover happened.
+     */
+    private rollCycleIfNeeded;
+    private scheduleWrite;
+    private flush;
+    private load;
+    private disposeLocal;
+    private safeSplit;
+}
+export default TokenQuotaService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,410 @@
+/**
+ * Daily per-model token quota enforcement and accounting for the harness.
+ *
+ * The service owns three responsibilities, all driven by the existing agent
+ * and session extension points — no loop modification:
+ *
+ * 1. **Accounting** — folds each live session's `request/header` to learn the
+ *    `provider/model` in use, and credits the combined input + output + cache
+ *    token count of every `assistant/message` that reports provider usage into
+ *    that model's current-UTC-day bucket. Counters persist to a JSON file
+ *    under the Harness home and roll over automatically at UTC midnight.
+ *
+ * 2. **Enforcement** — on the `agent/request` waterfall it awaits the resolved
+ *    call config, and when the selected model's daily usage is at or above its
+ *    configured cap (a positive limit), it throws an {@link LlmError} with
+ *    `TOKEN_QUOTA_EXCEEDED`, ending the turn before any provider request is
+ *    dispatched. A limit of `0` (or no entry) leaves the model unlimited.
+ *
+ * 3. **Limits + pull** — per-model limits live in the settings document
+ *    (`token-quota` namespace, written by the Web panel through the settings
+ *    scope); every change re-reads them. The current snapshot is served to
+ *    consumers over a plugin-owned HTTP route (`GET /token-quota`, registered
+ *    on the existing `webServer` service when one exists); the browser panel
+ *    polls it, so no core-Harness wiring or generated RPC contract is needed.
+ *
+ * The browser half (`src/client/`) renders a floating panel from the polled
+ * snapshot and writes limits back through the settings scope; this module
+ * stays browser-free (the optional route is plain node:http).
+ *
+ * @module @jxgame2020/dsh-token-quota
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+// Type-only side-effect: pulls agent/request and agent/pre-step Events augmentations
+// the service listens to without importing any runtime value.
+import '@deepseek-ai/dsh-agent';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { TOKEN_QUOTA_EXCEEDED_CODE, TOKEN_QUOTA_NAMESPACE, tokenQuotaKey, } from "./types.js";
+import { assertTokenQuotaLimit, splitTokenQuotaKey } from "./invariant.js";
+/** Settings schema resolving the per-model daily caps document. */
+const TOKEN_QUOTA_SETTINGS_SCHEMA = z.object({
+    limits: z.dict(z.number().step(1).min(0)).default({}),
+    monitored: z.array(z.string()).default([]),
+    onFull: z.union(['stop', 'switchQuota', 'switchAll', 'switchPriority']).default('stop'),
+    // `reset` is a user-facing preference outside the validated surface: the
+    // panel writes it and the host validates the shape at runtime. `z.any` with
+    // a null default keeps it out of the strict fields above.
+    reset: z.any().default(null),
+});
+/** Two-digit zero-pad helper. */
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+/** The machine's own UTC offset in whole hours (default reset timezone). */
+function localOffsetHours(now = new Date()) {
+    return -now.getTimezoneOffset() / 60;
+}
+/**
+ * Resolve the reset-cycle key a timestamp belongs to: the `YYYY-MM-DD@HH:MM`
+ * label (in the configured timezone) of the cycle whose `hour:minute` reset
+ * moment contains the timestamp. With the default config (machine timezone,
+ * 00:00) this reproduces the historical "resets at machine midnight".
+ */
+function cycleKey(now, reset) {
+    const offsetMs = reset.offsetHours * 3_600_000;
+    const zoned = new Date(now.getTime() + offsetMs);
+    const zonedDayStartUtc = Date.UTC(zoned.getUTCFullYear(), zoned.getUTCMonth(), zoned.getUTCDate()) - offsetMs;
+    const resetMinutes = reset.hour * 60 + reset.minute;
+    const cycleStartToday = zonedDayStartUtc + resetMinutes * 60_000;
+    const cycleStartUtc = now.getTime() >= cycleStartToday
+        ? cycleStartToday
+        : cycleStartToday - 86_400_000;
+    const startZoned = new Date(cycleStartUtc + offsetMs);
+    return `${startZoned.getUTCFullYear()}-${pad2(startZoned.getUTCMonth() + 1)}-${pad2(startZoned.getUTCDate())}@${pad2(reset.hour)}:${pad2(reset.minute)}`;
+}
+/** Default counter file under the Harness home (overridable through config). */
+function defaultStoragePath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'token-quota.json');
+}
+/** Combined input + output + cache token count of one provider usage report. */
+function usageTokens(usage) {
+    return usage.inputTokens
+        + (usage.cacheReadTokens ?? 0)
+        + (usage.cacheWriteTokens ?? 0)
+        + usage.outputTokens;
+}
+/**
+ * Daily token-quota service.
+ *
+ * Mount it beside the other rows (`@jxgame2020/dsh-token-quota`) and write
+ * per-model limits through the `token-quota` settings namespace.
+ */
+export class TokenQuotaService extends Service {
+    static Config = z.object({
+        storagePath: z.string().default(''),
+    });
+    storagePath;
+    reset = {
+        offsetHours: localOffsetHours(),
+        hour: 0,
+        minute: 0,
+    };
+    cycle = cycleKey(new Date(), this.reset);
+    usage = {};
+    history = {};
+    limits = {};
+    monitored = undefined;
+    settingsSource = () => ({ limits: {}, monitored: [], onFull: 'stop' });
+    /** Per-session folded model key from the latest `request/header`. */
+    headerKeys = new WeakMap();
+    writeTimer;
+    /** Disposer for the optional HTTP snapshot route (`GET /token-quota`). */
+    disposeRoute;
+    /** Disposer for the optional usage-history route (`GET /token-quota/log`). */
+    disposeRouteLog;
+    /** Disposer for the webServer-arrival watcher when the service mounts later. */
+    disposeRouteWatcher;
+    /**
+     * @param ctx - owning context (events and the settings section register on it).
+     * @param config - optional counter path.
+     */
+    constructor(ctx, config = {}) {
+        super(ctx, 'tokenQuota');
+        this.storagePath = config.storagePath !== undefined && config.storagePath.length > 0
+            ? config.storagePath
+            : defaultStoragePath();
+        this.load();
+        // Limits live in the user settings document; the Web panel writes them and
+        // the section watcher pushes every change back here.
+        installSettingsSection(ctx, settingsNamespace(TOKEN_QUOTA_NAMESPACE), TOKEN_QUOTA_SETTINGS_SCHEMA, { limits: {} }, {
+            setSource: (current) => {
+                // Normalize the resolved (schema-shaped) document into the plugin's
+                // required shape: empty monitored = monitor everything, absent onFull
+                // falls back to 'stop'.
+                this.settingsSource = () => {
+                    const doc = current();
+                    return {
+                        limits: doc.limits ?? {},
+                        monitored: doc.monitored ?? [],
+                        onFull: doc.onFull ?? 'stop',
+                        reset: doc.reset ?? undefined,
+                    };
+                };
+            },
+            validate: (value) => {
+                for (const [key, limit] of Object.entries(value.limits ?? {})) {
+                    assertTokenQuotaLimit(limit, key);
+                    splitTokenQuotaKey(key);
+                }
+            },
+            onChange: () => {
+                const doc = this.settingsSource();
+                this.limits = { ...doc.limits };
+                this.monitored = doc.monitored !== undefined && doc.monitored.length > 0
+                    ? new Set(doc.monitored)
+                    : undefined;
+                if (doc.reset !== undefined
+                    && typeof doc.reset === 'object'
+                    && doc.reset !== null
+                    && typeof doc.reset.offsetHours === 'number'
+                    && typeof doc.reset.hour === 'number'
+                    && typeof doc.reset.minute === 'number') {
+                    const configured = doc.reset;
+                    this.reset = {
+                        offsetHours: Math.max(-12, Math.min(14, Math.round(configured.offsetHours))),
+                        hour: Math.max(0, Math.min(23, Math.round(configured.hour))),
+                        minute: Math.max(0, Math.min(59, Math.round(configured.minute))),
+                    };
+                    this.rollCycleIfNeeded();
+                }
+                else {
+                    // null / malformed (unset) = machine-local midnight — the default.
+                    this.reset = { offsetHours: localOffsetHours(), hour: 0, minute: 0 };
+                    this.rollCycleIfNeeded();
+                }
+            },
+        });
+        // Snapshot route: optional — only mounted when a webServer service exists
+        // (the Web profile); headless deployments keep the enforcement without it.
+        this.tryMountRoute();
+        if (this.disposeRoute === undefined) {
+            this.disposeRouteWatcher = ctx.on('internal/service', (name) => {
+                if (name === 'webServer')
+                    this.tryMountRoute();
+            });
+        }
+        // Accounting: learn the model from each request header, credit usage on
+        // every provider-reported assistant message for that model.
+        ctx.on('session/event', (session, event) => {
+            this.onSessionEvent(session, event);
+        });
+        // Enforcement + accounting lock: the waterfall's resolved config is the
+        // authoritative model for this request — bind it to the agent's session
+        // so a model switch mid-flight never misattributes the in-flight reply.
+        ctx.on('agent/request', async (payload, next) => this.onRequest(payload, next));
+        ctx.effect(() => () => { this.disposeLocal(); }, 'token-quota: flush on unload');
+    }
+    /** Serve the current snapshot over the plugin-owned HTTP route. */
+    tryMountRoute() {
+        const server = this.ctx.get('webServer');
+        if (server === undefined || this.disposeRoute !== undefined)
+            return;
+        this.disposeRoute = server.register({
+            kind: 'exact',
+            path: '/token-quota',
+            handler: (_req, res) => {
+                const body = JSON.stringify(this.readSnapshot());
+                res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+                res.end(body);
+            },
+        });
+        this.disposeRouteLog = server.register({
+            kind: 'exact',
+            path: '/token-quota/log',
+            handler: (_req, res) => {
+                const body = JSON.stringify(this.readLog());
+                res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+                res.end(body);
+            },
+        });
+    }
+    /** Read the full per-cycle usage history (log dialog data). */
+    readLog() {
+        this.rollCycleIfNeeded();
+        const entries = [];
+        for (const [cycle, usageByKey] of Object.entries(this.history)) {
+            for (const [key, used] of Object.entries(usageByKey)) {
+                const parts = this.safeSplit(key);
+                if (parts === undefined || used <= 0)
+                    continue;
+                entries.push({ day: cycle, key, provider: parts.provider, model: parts.model, used });
+            }
+        }
+        // Include the current cycle's live counters too.
+        for (const [key, used] of Object.entries(this.usage)) {
+            const parts = this.safeSplit(key);
+            if (parts === undefined || used <= 0)
+                continue;
+            entries.push({ day: this.cycle, key, provider: parts.provider, model: parts.model, used });
+        }
+        entries.sort((left, right) => right.day.localeCompare(left.day) || left.key.localeCompare(right.key));
+        return { entries };
+    }
+    /** Read the current snapshot (also used by tests and inspection). */
+    readSnapshot() {
+        this.rollCycleIfNeeded();
+        const keys = new Set([...Object.keys(this.usage), ...Object.keys(this.limits)]);
+        const entries = [];
+        for (const key of keys) {
+            const parts = this.safeSplit(key);
+            if (parts === undefined)
+                continue;
+            entries.push({
+                key,
+                provider: parts.provider,
+                model: parts.model,
+                used: this.usage[key] ?? 0,
+                limit: this.limitOf(key),
+            });
+        }
+        entries.sort((left, right) => left.key.localeCompare(right.key));
+        return { day: this.cycle, entries };
+    }
+    /** Today's used tokens for one model key, or `0`. */
+    usedToday(key) {
+        this.rollCycleIfNeeded();
+        return this.usage[key] ?? 0;
+    }
+    /** Whether a model is under active monitoring (undefined = every model). */
+    isMonitored(key) {
+        return this.monitored === undefined || this.monitored.has(key);
+    }
+    /** Resolve one model's daily cap: positive = capped, `0` = unlimited. */
+    limitOf(key) {
+        const limit = this.limits[key];
+        return typeof limit === 'number' && Number.isInteger(limit) && limit > 0 ? limit : 0;
+    }
+    onSessionEvent(session, event) {
+        if (event.type === 'request/header') {
+            const { provider, model } = event.data.header.config;
+            this.headerKeys.set(session, tokenQuotaKey(provider, model));
+            return;
+        }
+        if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+            const key = this.headerKeys.get(session);
+            if (key === undefined)
+                return;
+            if (!this.isMonitored(key))
+                return;
+            const tokens = usageTokens(event.data.usage);
+            if (tokens <= 0)
+                return;
+            this.rollCycleIfNeeded();
+            this.usage[key] = (this.usage[key] ?? 0) + tokens;
+            this.scheduleWrite();
+        }
+    }
+    async onRequest(payload, next) {
+        const config = await next();
+        const { provider, model } = config;
+        if (!provider || !model)
+            return config;
+        const key = tokenQuotaKey(provider, model);
+        // Bind the request's model to its session now (not on the later
+        // request/header append): an in-flight reply that lands after a model
+        // switch still credits the model that actually produced it.
+        this.headerKeys.set(payload.agent.session, key);
+        if (!this.isMonitored(key))
+            return config;
+        const limit = this.limitOf(key);
+        if (limit <= 0)
+            return config;
+        const used = this.usage[key] ?? 0;
+        if (used < limit)
+            return config;
+        throw new LlmError(`Daily token limit reached for "${provider}/${model}": ${used}/${limit} tokens used today. `
+            + 'Switch model in the quota panel or raise its limit.', TOKEN_QUOTA_EXCEEDED_CODE);
+    }
+    /**
+     * Roll over to a new reset cycle, archiving the finished cycle's counters
+     * into the history log, when the cycle key changed.
+     * @returns whether a rollover happened.
+     */
+    rollCycleIfNeeded() {
+        const now = cycleKey(new Date(), this.reset);
+        if (this.cycle === now)
+            return false;
+        if (Object.keys(this.usage).length > 0) {
+            this.history[this.cycle] = { ...this.usage };
+        }
+        this.cycle = now;
+        this.usage = {};
+        this.scheduleWrite();
+        return true;
+    }
+    scheduleWrite() {
+        if (this.writeTimer !== undefined)
+            return;
+        this.writeTimer = setTimeout(() => {
+            this.writeTimer = undefined;
+            this.flush();
+        }, 500);
+    }
+    flush() {
+        if (this.writeTimer !== undefined) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = undefined;
+        }
+        try {
+            mkdirSync(dirname(this.storagePath), { recursive: true });
+            writeFileSync(this.storagePath, JSON.stringify({
+                cycle: this.cycle,
+                usage: this.usage,
+                history: this.history,
+            }, null, 2));
+        }
+        catch (error) {
+            this.ctx.logger.warn('token-quota: failed to persist counters: %o', error);
+        }
+    }
+    load() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.storagePath, 'utf8'));
+            const candidate = parsed;
+            this.cycle = typeof candidate?.cycle === 'string' && candidate.cycle.length > 0
+                ? candidate.cycle
+                // Legacy files stored a bare `day` (machine-local date); adopt it as
+                // the current cycle so no usage is dropped on upgrade.
+                : typeof candidate?.day === 'string' && candidate.day.length > 0
+                    ? candidate.day
+                    : cycleKey(new Date(), this.reset);
+            const usage = candidate?.usage;
+            this.usage = typeof usage === 'object' && usage !== null && !Array.isArray(usage)
+                ? usage
+                : {};
+            const history = candidate?.history;
+            this.history = typeof history === 'object' && history !== null && !Array.isArray(history)
+                ? history
+                : {};
+            this.rollCycleIfNeeded();
+        }
+        catch {
+            // Missing or corrupt counter file starts fresh; it must never crash the harness.
+        }
+    }
+    disposeLocal() {
+        if (this.disposeRouteWatcher !== undefined)
+            this.disposeRouteWatcher();
+        if (this.disposeRoute !== undefined)
+            this.disposeRoute();
+        if (this.disposeRouteLog !== undefined)
+            this.disposeRouteLog();
+        this.flush();
+    }
+    safeSplit(key) {
+        try {
+            return splitTokenQuotaKey(key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+export default TokenQuotaService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime guards for the token-quota plugin's public boundary.
+ *
+ * A separate companion module keeps these reachable from both the Host and
+ * Client build faces without dragging the service implementation into a
+ * browser bundle.
+ *
+ * @module @jxgame2020/dsh-token-quota/invariant
+ */
+/** Accept one per-model daily limit: `0` (unlimited) or a positive integer. */
+export declare function assertTokenQuotaLimit(value: unknown, key: string): asserts value is number;
+/** Resolve a model key of the form `provider/model` into its two parts. */
+export declare function splitTokenQuotaKey(key: string): {
+    provider: string;
+    model: string;
+};
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,24 @@
+/**
+ * Runtime guards for the token-quota plugin's public boundary.
+ *
+ * A separate companion module keeps these reachable from both the Host and
+ * Client build faces without dragging the service implementation into a
+ * browser bundle.
+ *
+ * @module @jxgame2020/dsh-token-quota/invariant
+ */
+/** Accept one per-model daily limit: `0` (unlimited) or a positive integer. */
+export function assertTokenQuotaLimit(value, key) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new TypeError(`token-quota: limit for "${key}" must be a non-negative integer, received ${String(value)}`);
+    }
+}
+/** Resolve a model key of the form `provider/model` into its two parts. */
+export function splitTokenQuotaKey(key) {
+    const slash = key.indexOf('/');
+    if (slash <= 0 || slash === key.length - 1) {
+        throw new TypeError(`token-quota: invalid model key "${key}" — expected "provider/model"`);
+    }
+    return { provider: key.slice(0, slash), model: key.slice(slash + 1) };
+}
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared wire/type vocabulary for the daily token-quota plugin.
+ *
+ * The Host half owns the durable per-model daily counter and the enforcement
+ * gate; the browser half renders a floating panel from the snapshot it pulls
+ * over a plugin-owned HTTP route, and writes per-model limits and panel
+ * preferences through the settings document. This module is the one meeting
+ * point of the two planes: it carries strings and shapes only, never a
+ * runtime import from the other half.
+ *
+ * @module @jxgame2020/dsh-token-quota/types
+ */
+/** Settings namespace owning the per-model daily limits document. */
+export declare const TOKEN_QUOTA_NAMESPACE = "token-quota";
+/** Stable machine code thrown from `agent/request` when a model is over its daily cap. */
+export declare const TOKEN_QUOTA_EXCEEDED_CODE = "TOKEN_QUOTA_EXCEEDED";
+/**
+ * What to do once a monitored, quota-capped model reaches its daily cap.
+ * Selected in the panel's settings dialog; the panel acts on it (b/c/d auto
+ * switch, a stops and prompts).
+ */
+export declare const TOKEN_QUOTA_FULL_ACTIONS: readonly ["stop", "switchQuota", "switchAll", "switchPriority"];
+/** One of the {@link TOKEN_QUOTA_FULL_ACTIONS} values. */
+export type TokenQuotaFullAction = typeof TOKEN_QUOTA_FULL_ACTIONS[number];
+/**
+ * Daily reset moment: every day at `hour:minute` in the chosen timezone
+ * (a fixed UTC offset in hours, -12 through +14) the counters roll over.
+ * Absent from settings (or host default) means the machine's own timezone at
+ * midnight — the historical behaviour.
+ */
+export interface TokenQuotaReset {
+    /** Fixed UTC offset in whole hours, -12 .. +14. */
+    offsetHours: number;
+    /** Reset hour in that timezone, 0..23. */
+    hour: number;
+    /** Reset minute in that timezone, 0..59. */
+    minute: number;
+}
+/** Default reset: machine-local midnight (offset = host timezone, 00:00). */
+export declare const TOKEN_QUOTA_DEFAULT_RESET: TokenQuotaReset;
+/**
+ * Per-model daily-limit settings document shape. Keys are `provider/model`
+ * and a value of `0` (or an absent key) means unlimited for that model.
+ */
+export interface TokenQuotaSettings {
+    /**
+     * Daily token caps keyed by `provider/model`. `0` or absent = unlimited.
+     * Positive integers cap the combined input + output + cache token count
+     * for the current UTC day.
+     */
+    limits: Record<string, number>;
+    /**
+     * Model keys (`provider/model`) under active monitoring. An empty array
+     * means EVERY model is monitored (the install default). Unmonitored models
+     * are hidden from the panel, not metered, and never capped.
+     */
+    monitored: string[];
+    /**
+     * Behavior when a monitored, capped model hits its daily cap:
+     * `'stop'` stops and prompts, `'switchQuota'` auto-switches to another
+     * capped-but-available model, `'switchAll'` switches to any other available
+     * model, `'switchPriority'` prefers uncapped models then unmonitored ones.
+     */
+    onFull: TokenQuotaFullAction;
+    /**
+     * Daily reset moment (timezone + clock time). Absent = machine-local
+     * midnight (the historical behaviour).
+     */
+    reset?: TokenQuotaReset;
+}
+/** Token-quota plugin configuration. */
+export interface TokenQuotaConfig {
+    /**
+     * Counter JSON file path. Defaults to `token-quota.json` under the Harness
+     * home (`DSH_HOME` or `~/.dsh`).
+     */
+    storagePath?: string;
+}
+/** One model's live quota row, as rendered in the floating panel. */
+export interface TokenQuotaEntry {
+    /** Stable key `provider/model`; also the settings-document key. */
+    key: string;
+    /** Registered provider route. */
+    provider: string;
+    /** Provider-owned model id. */
+    model: string;
+    /** Tokens used today (input + output + cache). */
+    used: number;
+    /** Daily cap; `0` means unlimited. */
+    limit: number;
+}
+/**
+ * Full quota snapshot. The Host is the single fact source; the panel replaces
+ * its whole view on each pull, so replay is order-independent.
+ */
+export interface TokenQuotaSnapshot {
+    /** Reset-cycle key the counters belong to (`YYYY-MM-DD@HH:MM` in the reset timezone). */
+    day: string;
+    /** Per-model rows, sorted by key. */
+    entries: TokenQuotaEntry[];
+}
+/** One historical daily usage record, shown in the log dialog. */
+export interface TokenQuotaLogEntry {
+    /** Reset-cycle key (`YYYY-MM-DD@HH:MM`) the record belongs to. */
+    day: string;
+    /** Stable key `provider/model`. */
+    key: string;
+    /** Registered provider route. */
+    provider: string;
+    /** Provider-owned model id. */
+    model: string;
+    /** Tokens used that cycle (input + output + cache). */
+    used: number;
+}
+/**
+ * Full usage history: one entry per model per reset cycle with a record.
+ * Independent of the monitored set — every metered model appears.
+ */
+export interface TokenQuotaLog {
+    /** Entries sorted by day desc then key. */
+    entries: TokenQuotaLogEntry[];
+}
+/** Build the stable per-model key shared by the counter, settings, and snapshot. */
+export declare function tokenQuotaKey(provider: string, model: string): string;
+//# sourceMappingURL=types.d.ts.map