@linxin666/dsh-usage 0.3.7

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

@@ -0,0 +1,36 @@
+/**
+ * The usage statistics settings section: two tabs (用量: today's usage,
+ * balances, trend; 个人套餐: per-provider plan quota windows) plus a compact
+ * settings row. Data comes from the host's loopback-fenced
+ * /api/dsh-usage/overview document; polling runs only while the section is
+ * mounted and the tab is visible.
+ * @module @linxin666/dsh-usage/client/UsageSectionCard
+ */
+import { type ReactNode } from 'react';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { UsageStoreInstance } from './usage-store.ts';
+/** The settings fields this section edits (immediate-apply semantics). */
+export interface UsageSettings {
+    enabled?: boolean;
+    pollIntervalSec?: number;
+    bubbleMode?: string;
+}
+/** The registration-side face the section's slot entry injects. */
+export interface UsageSectionFace {
+    /** The section-local store (overview snapshot + lifecycle). */
+    store: UsageStoreInstance;
+    /** Fetch one overview now. */
+    poll: () => void;
+    /** Force a host probe cycle now (resolves with the fresh overview). */
+    refresh: () => void;
+    /** Whether a forced refresh is in flight (component-local state mirrors it). */
+    settings: SettingsScope<UsageSettings>;
+}
+export interface UsageSectionProps extends UsageSectionFace {
+    /** Close the settings panel (the shell owns the open state). */
+    close: () => void;
+}
+/** Compact token count: 12345 -> 12.3k, 1234567 -> 1.23M. */
+export declare function formatTokens(value: number): string;
+/** The section component; the slot merges the face into these props. */
+export declare function UsageSectionCard(props: UsageSectionProps): ReactNode;

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

@@ -0,0 +1,34 @@
+/**
+ * dsh-usage browser half — seats the first-level 使用统计 settings section
+ * (below the Workshop entry) and polls the host overview only while the
+ * section is open. All provider probing and credential handling happens in
+ * the host half; this bundle only renders the overview document.
+ * @module @linxin666/dsh-usage/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type UsageSettings } from './UsageSectionCard.tsx';
+/** Required services. */
+export declare const inject: string[];
+export type { UsageSectionProps, UsageSectionFace } from './UsageSectionCard.tsx';
+export type { UsageUiState } from './usage-store.ts';
+export type { UsageSettings };
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /**
+         * Optional rc.6 compatibility binder provided by dsh-web-settings;
+         * absent when that group plugin is not installed, so callers fall back to
+         * the official settings scope.
+         */
+        webUiSettings?: {
+            bind<S>(spec: SettingsScopeSpec<S>): SettingsScope<S>;
+        };
+    }
+}
+/**
+ * Client plugin body: register dictionaries and seat the settings section.
+ * The overview poll loop and the store live with the section component's
+ * mount cycle, so no background traffic exists while the page is closed.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

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

@@ -0,0 +1,62 @@
+/**
+ * dsh-usage locale dictionaries (zh/en). The zh dictionary is the key source;
+ * `en` mirrors its full key set (packages/AGENTS.md bilingual discipline).
+ * @module @linxin666/dsh-usage/client/locales
+ */
+/** Dictionary namespace this package registers. */
+export declare const NS = "dsh-web-ui-usage";
+/** Chinese copy. */
+export declare const zh: {
+    'usage.title': string;
+    'usage.tab.usage': string;
+    'usage.tab.plans': string;
+    'usage.refresh': string;
+    'usage.refreshing': string;
+    'usage.updated': string;
+    'usage.loading': string;
+    'usage.error': string;
+    'usage.current': string;
+    'usage.today': string;
+    'usage.calls': string;
+    'usage.tokens.total': string;
+    'usage.tokens.input': string;
+    'usage.tokens.output': string;
+    'usage.tokens.cacheRead': string;
+    'usage.tokens.cacheWrite': string;
+    'usage.trend': string;
+    'usage.noData': string;
+    'usage.balance': string;
+    'usage.balance.unsupported': string;
+    'usage.balance.noCredential': string;
+    'usage.oauth': string;
+    'usage.plan.reset': string;
+    'usage.plan.noPlan': string;
+    'usage.plan.windows.5h': string;
+    'usage.plan.windows.week': string;
+    'usage.plan.windows.month': string;
+    'usage.provider.error': string;
+    'usage.config.title': string;
+    'usage.config.enabled': string;
+    'usage.config.pollIntervalSec': string;
+    'usage.config.bubbleMode': string;
+    'usage.config.bubbleMode.always': string;
+    'usage.config.bubbleMode.change': string;
+    'usage.config.bubbleMode.off': string;
+};
+/** English mirror; every zh key present. */
+export declare const en: Record<UsageKey, string>;
+export type UsageKey = keyof typeof zh;
+/**
+ * Active dictionary, picked by the document language at call time. The
+ * section resolves its copy the same tiny way the pet's DOM-injected surface
+ * does (the settings section has no framework locale seat of its own).
+ */
+export declare function dictionary(): Record<UsageKey, string>;
+/** Translate a key with optional `{name}` template params; missing keys degrade to the key. */
+export declare function t(key: string, params?: Record<string, unknown>): string;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** dsh-usage UI copy. */
+        'dsh-web-ui-usage': UsageKey;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Browser-side usage store: the overview snapshot polled from the host plus
+ * the fetch lifecycle. Section-local: the store lives while the settings
+ * section is mounted, so polling only runs while the page is open.
+ * @module @linxin666/dsh-usage/client/usage-store
+ */
+import type { EngineStoreHandle, EngineStoreInstance } from '@deepseek-ai/dsh-client-store';
+import type { UsageOverviewView } from '../core/types.ts';
+/** Section UI state as consumers see it. */
+export interface UsageUiState {
+    /** Latest host overview; null before the first successful fetch. */
+    snapshot: UsageOverviewView | null;
+    /** Fetch lifecycle. */
+    status: 'loading' | 'ready' | 'error';
+    /** Transport error message, when any. */
+    error: string | null;
+}
+/** Store write set. */
+export type UsageUiActions = {
+    /** Replace the overview (poll result). */
+    setSnapshot: (draft: UsageUiState, snapshot: UsageOverviewView) => void;
+    /** Mark the fetch lifecycle. */
+    setState: (draft: UsageUiState, status: UsageUiState['status'], error: string | null) => void;
+};
+/** Create the usage store handle (apply world only; never module-level). */
+export declare function createUsageStore(): EngineStoreHandle<UsageUiState, UsageUiActions>;
+export type UsageStoreInstance = EngineStoreInstance<UsageUiState, UsageUiActions>;

package/lib/types/core/adapters.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Provider adapters: one entry per provider family this plugin can query for
+ * a pay-as-you-go balance or a coding-plan quota. Adapters are pure — they
+ * build an HTTP probe from a resolved credential and parse the response — so
+ * the service stays transport-only and every endpoint detail lives here.
+ *
+ * All probes run host-side (Node fetch); API keys never reach the browser.
+ * @module @linxin666/dsh-usage/core/adapters
+ */
+import type { PlanWindowView } from './types.ts';
+/** One HTTP probe the service executes verbatim. */
+export interface ProbeSpec {
+    url: string;
+    headers: Record<string, string>;
+}
+/** Inputs an adapter may use to build a probe. */
+export interface AdapterProbeContext {
+    /** Resolved credential value (the raw key; env refs are resolved upstream). */
+    apiKey: string;
+}
+/** A parsed balance fact. */
+export interface BalanceParse {
+    currency: string;
+    totalBalance: string;
+}
+/** A parsed plan-quota fact. */
+export interface PlanParse {
+    planName?: string;
+    windows: PlanWindowView[];
+}
+/** One provider family's probing capability. */
+export interface ProviderAdapter {
+    /** Provider route keys this adapter serves. */
+    ids: readonly string[];
+    /** Fallback display name when the LLM runtime has none. */
+    displayName: string;
+    balance?: {
+        build(context: AdapterProbeContext): ProbeSpec;
+        parse(status: number, body: unknown): BalanceParse | undefined;
+    };
+    plan?: {
+        build(context: AdapterProbeContext): ProbeSpec;
+        parse(status: number, body: unknown): PlanParse | undefined;
+    };
+}
+/**
+ * The adapter registry, in no particular order. Route keys come from the
+ * pi-ai provider catalog plus the routes this deployment observed in user
+ * configuration (`zenmux`).
+ */
+export declare const PROVIDER_ADAPTERS: readonly ProviderAdapter[];
+/** Find the adapter serving a provider route key, if any. */
+export declare function adapterFor(provider: string): ProviderAdapter | undefined;
+/**
+ * Best-effort human message from a provider error body, for the per-provider
+ * error line. Never throws; truncated to one short sentence.
+ */
+export declare function providerErrorMessage(status: number, body: unknown): string;

package/lib/types/core/ledger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The usage ledger: a pure fold from session usage facts into a per-day,
+ * per-provider, per-model totals document, plus its JSON serialization.
+ * Host-side state lives only in the document; the service owns persistence.
+ * @module @linxin666/dsh-usage/core/ledger
+ */
+import { type UsageLedgerDocument, type UsageTokenTotals } from './types.ts';
+/** Local-date key (`YYYY-MM-DD`) for an epoch ms timestamp. */
+export declare function localDateKey(ms: number): string;
+/** An empty ledger document. */
+export declare function createLedgerDocument(): UsageLedgerDocument;
+/**
+ * Fold one usage report into the ledger in place. `provider` is the route key
+ * and `model` the provider-owned model id the step ran under.
+ */
+export declare function foldUsage(doc: UsageLedgerDocument, atMs: number, provider: string, model: string, usage: Readonly<UsageTokenTotals>): void;
+/** Total tokens of a bucket (billed input + output; reasoning is inside output). */
+export declare function totalTokens(totals: Readonly<UsageTokenTotals>): number;
+/** All local-date keys in the ledger, ascending. */
+export declare function ledgerDayKeys(doc: Readonly<UsageLedgerDocument>): string[];
+/**
+ * Drop every day older than `retainDays` local days before `todayKey`, in
+ * place. Returns the number of pruned days.
+ */
+export declare function pruneLedger(doc: UsageLedgerDocument, todayKey: string, retainDays: number): number;
+/**
+ * Parse a ledger document from untrusted JSON: unknown shapes resolve to an
+ * empty document, malformed entries are dropped, numbers are coerced to
+ * finite values. Never throws.
+ */
+export declare function deserializeLedger(value: unknown): UsageLedgerDocument;

package/lib/types/core/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Wire-facing view types shared by the dsh-usage host service, its HTTP
+ * routes, and the browser section. Everything here crosses the wire as JSON
+ * and must stay provider-agnostic: provider quirks are normalized inside the
+ * core adapters, never here.
+ * @module @linxin666/dsh-usage/core/types
+ */
+/** One disjoint token bucket total, aggregated over calls (billed input = input + cacheRead + cacheWrite). */
+export interface UsageTokenTotals {
+    /** Uncached input tokens. */
+    inputTokens: number;
+    /** Output tokens (reasoning included). */
+    outputTokens: number;
+    /** Cache read tokens. */
+    cacheReadTokens: number;
+    /** Cache write tokens. */
+    cacheWriteTokens: number;
+    /** Reasoning tokens, when the provider reported them. */
+    reasoningTokens: number;
+    /** Provider calls that reported usage. */
+    calls: number;
+}
+/** A zeroed totals bucket. */
+export declare function emptyTotals(): UsageTokenTotals;
+/** Add `right` into `left` in place. */
+export declare function addTotals(left: UsageTokenTotals, right: Readonly<UsageTokenTotals>): UsageTokenTotals;
+/** On-disk usage ledger: per local day, per provider route, per model. */
+export interface UsageLedgerDocument {
+    version: 1;
+    /** Local-date key `YYYY-MM-DD` → per-provider per-model totals. */
+    days: Record<string, Record<string, Record<string, UsageTokenTotals>>>;
+}
+/** One provider row of the day summary the overview serves. */
+export interface UsageProviderSummary {
+    provider: string;
+    totals: UsageTokenTotals;
+    /** Per-model breakdown, heaviest by total tokens first, capped by the route. */
+    models: Array<{
+        model: string;
+        totals: UsageTokenTotals;
+    }>;
+}
+/** One day row of the trend the overview serves. */
+export interface UsageDaySummary {
+    date: string;
+    totals: UsageTokenTotals;
+}
+/** A balance fact normalized from a provider probe. */
+export interface BalanceView {
+    /** ISO 4217 code the provider bills in (`CNY`, `USD`, ...). */
+    currency: string;
+    /** Spendable total formatted for display (no currency symbol). */
+    totalBalance: string;
+    /** Epoch ms of the successful probe. */
+    updatedAt: number;
+}
+/** One quota window of a coding plan. */
+export interface PlanWindowView {
+    /** Stable window key the UI localizes (`5h`, `week`, `month`, provider strings otherwise). */
+    key: string;
+    /** Provider-supplied window name, when it sends one. */
+    name?: string;
+    /** Used percent 0-100, when computable. */
+    percent?: number;
+    /** ISO 8601 reset instant, when the provider reports one. */
+    resetsAt?: string;
+}
+/** A coding-plan quota fact normalized from a provider probe. */
+export interface PlanView {
+    /** Plan tier name, when the provider reports one. */
+    planName?: string;
+    windows: PlanWindowView[];
+    updatedAt: number;
+}
+/** How the credential backing one provider route was resolved. */
+export type CredentialKind = 'api-key' | 'env' | 'oauth' | 'none';
+/** One provider row of the overview snapshot. */
+export interface ProviderSnapshotView {
+    /** Provider route key (`deepseek`, `kimi-coding`, custom routes, ...). */
+    provider: string;
+    /** Display name from the LLM runtime, else the adapter's, else the route key. */
+    displayName: string;
+    credential: CredentialKind;
+    /** Whether a balance/plan adapter exists for this route. */
+    supported: boolean;
+    balance?: BalanceView;
+    plan?: PlanView;
+    /** Last probe failure, cleared on the next success. */
+    error?: string;
+    updatedAt?: number;
+}
+/** The overview the browser section renders. */
+export interface UsageOverviewView {
+    updatedAt: number;
+    providers: ProviderSnapshotView[];
+    /** The provider the pet bubble and the header highlight; `source` says how it was picked. */
+    current: {
+        provider?: string;
+        model?: string;
+        /** `live` — last request seen this boot; `default` — the agent default model. */
+        source: 'live' | 'default';
+    };
+    usage: {
+        today: {
+            date: string;
+            totals: UsageTokenTotals;
+            providers: UsageProviderSummary[];
+        };
+        /** Last N local days ascending, including today. */
+        days: UsageDaySummary[];
+    };
+}

package/lib/types/dsh-home.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Resolve the DSH home directory from the live environment. */
+export declare function dshHome(): string;

package/lib/types/host/http.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
+ * family's route module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-shared/host/http
+ */
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http';
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export declare function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown>;
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export declare function readJsonBody(req: IncomingMessage, opts?: {
+    maxBytes?: number;
+    objectOnly?: boolean;
+}): Promise<unknown | null>;
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown, headers?: OutgoingHttpHeaders): void;

package/lib/types/host/loopback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-shared/host/loopback
+ */
+import type { IncomingMessage } from 'node:http';
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export declare function isIPv4Loopback(v4: string): boolean;
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;

package/lib/types/host/routes.d.ts

@@ -0,0 +1,14 @@
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { UsageService } from './usage-service.ts';
+export declare const USAGE_API_PREFIX = "/api/dsh-usage";
+/**
+ * Loopback-fenced overview route: provider balances, plan quotas, and token
+ * usage totals. Personal account data, so the loopback fence mirrors
+ * dsh-perf's stats surface; the browser runs on the same machine.
+ */
+export declare function makeUsageOverviewRoute(service: UsageService): WebRoute;
+/**
+ * Loopback-fenced manual refresh: forces one probe cycle now and answers
+ * with the fresh overview.
+ */
+export declare function makeUsageRefreshRoute(service: UsageService): WebRoute;

package/lib/types/host/usage-service.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The dsh-usage host service: folds live session usage into the persistent
+ * ledger, probes each configured provider's balance/coding-plan endpoint on
+ * a poll cycle, and announces the current provider's status to the pet
+ * bubble. Secrets stay in the host process; the browser only ever sees the
+ * overview document.
+ * @module @linxin666/dsh-usage/host/usage-service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { UsageOverviewView } from '../core/types.ts';
+/** Source tag the plugin stamps onto pet announcements. */
+export declare const USAGE_ANNOUNCE_SOURCE = "dsh-usage";
+/** Poll-loop and announce options; re-applied live on settings change. */
+export interface UsageServiceOptions {
+    pollIntervalSec: number;
+    bubbleMode: 'always' | 'change' | 'off';
+    retainDays: number;
+}
+/** Format a balance for display: symbol prefix when known, code suffix otherwise. */
+export declare function formatMoney(currency: string, totalBalance: string): string;
+/** Map a used percent to the announcement tone. */
+export declare function planTone(percent: number): 'ok' | 'warn' | 'low';
+export declare class UsageService {
+    private readonly ctx;
+    private options;
+    private readonly persistDir;
+    private readonly ledgerPath;
+    private readonly snapshotsPath;
+    private ledger;
+    private readonly snapshots;
+    /** Per-live-session route attribution (WeakMap: disposed sessions age out). */
+    private readonly sessionRoutes;
+    /** The most recent route seen this boot; the pet bubble follows it. */
+    private current;
+    private sessionListenerDisposer;
+    private pollTimer;
+    private flushTimer;
+    private pollInFlight;
+    private disposed;
+    private lastSignature;
+    constructor(ctx: Context, options: UsageServiceOptions);
+    /** Start the listeners, load persisted state, and arm the first poll. */
+    start(): void;
+    /** Stop timers and flush pending ledger writes. */
+    stop(): void;
+    /** Re-apply options live (settings change); the poll cycle picks them up. */
+    applyOptions(options: UsageServiceOptions): void;
+    /** Force one poll now (manual refresh route). */
+    refresh(): Promise<void>;
+    /** Assemble the overview document the browser section renders. */
+    overview(): UsageOverviewView;
+    /** One local day aggregated per provider. */
+    private daySummary;
+    private onSessionEvent;
+    /** Normalize a provider TokenUsage into the ledger bucket (one call). */
+    private totalsFrom;
+    private loadPersisted;
+    private scheduleFlush;
+    private flushLedger;
+    private persistSnapshots;
+    private rearmPoll;
+    /** One poll cycle: enumerate routes, resolve credentials, probe, announce. */
+    pollNow(): Promise<void>;
+    private listProviderRoutes;
+    private probeRoute;
+    /**
+     * Resolve the credential backing one route: pi-ai credential records
+     * first, then the profile's apiKeyEnv reference, then the DeepSeek
+     * official adapter's env reference. OAuth grants resolve to a kind with
+     * no key (this plugin does not spend third-party OAuth budgets).
+     */
+    private resolveCredential;
+    /** The llm-pi-ai profile object for one provider route, when configured. */
+    private piAiProfile;
+    /** The DeepSeek official adapter's credential reference name. */
+    private deepseekApiKeyEnv;
+    /**
+     * Announce the current provider's balance or plan usage to the pet. In
+     * `change` mode only meaningful value changes re-announce; `off` skips.
+     */
+    private announceCurrent;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from 'schemastery';
+import { type UsageServiceOptions } from './host/usage-service.ts';
+export declare const name = "dsh-usage";
+export declare const inject: string[];
+export declare const USAGE_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export interface Config {
+    enabled?: boolean;
+    /** Provider probe cycle in seconds; 30-3600. */
+    pollIntervalSec?: number;
+    /** Pet bubble mode: always (refreshes each poll), change (only on value change), off. */
+    bubbleMode?: string;
+    /** Ledger retention in local days. */
+    retainDays?: number;
+}
+export declare const Config: z<Config>;
+export interface ResolvedConfig extends UsageServiceOptions {
+    enabled: boolean;
+}
+export declare function resolveConfig(config?: Config): ResolvedConfig;
+export declare const apply: (ctx: Context, config?: Config) => void;

package/lib/types/mount-once.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export declare function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T;