@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/usage/limits/normalize.js

@@ -0,0 +1,211 @@
+const headersOf = (input) => {
+    const map = new Map();
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value === 'string' && value.trim())
+            map.set(key.toLowerCase(), value.trim());
+    }
+    return map;
+};
+export function toNumber(value) {
+    if (value === undefined)
+        return null;
+    const cleaned = value.replace(/[%,\s]/g, '');
+    if (!cleaned)
+        return null;
+    const parsed = Number(cleaned);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** A reset time as an ISO instant: epoch seconds or milliseconds, a duration, or a date string. */
+export function toIso(value, now) {
+    if (!value)
+        return null;
+    const text = value.trim();
+    const duration = /^(?:(\d+(?:\.\d+)?)d)?(?:(\d+(?:\.\d+)?)h)?(?:(\d+(?:\.\d+)?)m)?(?:(\d+(?:\.\d+)?)s)?(?:(\d+(?:\.\d+)?)ms)?$/i.exec(text);
+    if (duration && text.match(/[a-z]/i)) {
+        const [, d, h, m, s, ms] = duration;
+        const total = Number(d ?? 0) * 86_400_000 + Number(h ?? 0) * 3_600_000 + Number(m ?? 0) * 60_000 + Number(s ?? 0) * 1_000 + Number(ms ?? 0);
+        if (Number.isFinite(total) && total > 0)
+            return new Date(now.getTime() + total).toISOString();
+    }
+    const numeric = /^\d+(?:\.\d+)?$/.test(text) ? Number(text) : Number.NaN;
+    if (Number.isFinite(numeric)) {
+        const millis = numeric > 10_000_000_000 ? numeric : numeric * 1_000;
+        const date = new Date(millis);
+        if (!Number.isNaN(date.getTime()))
+            return date.toISOString();
+    }
+    const parsed = Date.parse(text);
+    return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+const leftPercent = (usedPercent) => usedPercent === null ? null : Math.max(0, Math.min(100, 100 - usedPercent));
+const statusFor = (percent, fallback = 'allowed') => percent === null ? fallback : percent >= 100 ? 'rejected' : percent >= 80 ? 'warning' : 'allowed';
+function entry(limit, observedAt) {
+    return { ...limit, provider: limit.provider, observedAt };
+}
+/** The four well-known families, with their labels and units. */
+const ANTHROPIC_FAMILIES = [
+    { key: 'requests', label: 'Requests', unit: 'requests' },
+    { key: 'input-tokens', label: 'Input tokens', unit: 'tokens' },
+    { key: 'output-tokens', label: 'Output tokens', unit: 'tokens' }
+];
+const RATE_FAMILIES = ['requests', 'tokens', 'input-tokens', 'output-tokens', 'tokens-per-minute'];
+const title = (value) => value.split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+/**
+ * Reads every limit family present in one provider response. `provider` is the Pi provider id;
+ * the returned ids are namespaced with it so two providers never overwrite each other.
+ */
+export function normalizeHeaders(provider, response, now = new Date()) {
+    const headers = headersOf(response.headers);
+    const observedAt = now.toISOString();
+    const limits = new Map();
+    const put = (limit) => { limits.set(limit.id, limit); };
+    // Anthropic's per-resource rate limits.
+    for (const family of ANTHROPIC_FAMILIES) {
+        const prefix = `anthropic-ratelimit-${family.key}-`;
+        const limit = toNumber(headers.get(`${prefix}limit`));
+        const remaining = toNumber(headers.get(`${prefix}remaining`));
+        const resetsAt = toIso(headers.get(`${prefix}reset`), now);
+        if (limit === null && remaining === null && !resetsAt)
+            continue;
+        const used = limit !== null && remaining !== null ? Math.max(0, limit - remaining) : null;
+        const usedPercent = limit !== null && limit > 0 && used !== null ? (used / limit) * 100 : null;
+        put(entry({
+            id: `${provider}:${family.key}`,
+            label: family.label,
+            provider,
+            kind: 'rate',
+            unit: family.unit,
+            used,
+            limit,
+            remaining,
+            usedPercent,
+            remainingPercent: leftPercent(usedPercent),
+            resetsAt,
+            status: statusFor(usedPercent),
+            source: 'headers'
+        }, observedAt));
+    }
+    // Anthropic's unified window headers for subscription plans.
+    const unified = new Map();
+    for (const [key, value] of headers) {
+        const match = /^anthropic-ratelimit-unified-(.+?)-(utilization|reset|status)$/.exec(key);
+        if (!match)
+            continue;
+        const window = match[1];
+        const bucket = unified.get(window) ?? {};
+        bucket[match[2]] = value;
+        unified.set(window, bucket);
+    }
+    const unifiedStatus = headers.get('anthropic-ratelimit-unified-status');
+    for (const [window, bucket] of unified) {
+        const raw = toNumber(bucket.utilization);
+        const usedPercent = raw === null ? null : raw <= 1.5 ? raw * 100 : raw;
+        const id = `${provider}:window-${window}`;
+        put(entry({
+            id,
+            label: window === '5h' ? '5-hour window' : window === '7d' ? 'Weekly window' : window === 'primary' ? 'Primary window' : window === 'secondary' ? 'Secondary window' : `${title(window)} window`,
+            provider,
+            kind: 'window',
+            unit: 'percent',
+            usedPercent,
+            remainingPercent: leftPercent(usedPercent),
+            resetsAt: toIso(bucket.reset, now),
+            status: bucket.status ?? (unifiedStatus === 'rejected' ? 'rejected' : statusFor(usedPercent)),
+            source: 'headers'
+        }, observedAt));
+    }
+    // Codex-style plan windows.
+    for (const window of ['primary', 'secondary']) {
+        const percent = toNumber(headers.get(`x-codex-${window}-used-percent`));
+        const windowMinutes = toNumber(headers.get(`x-codex-${window}-window-minutes`));
+        const resetsAt = toIso(headers.get(`x-codex-${window}-reset-at`) ?? headers.get(`x-codex-${window}-reset`), now);
+        if (percent === null && !resetsAt)
+            continue;
+        put(entry({
+            id: `${provider}:codex-${window}`,
+            label: `${title(window)} window`,
+            provider,
+            kind: 'window',
+            unit: 'percent',
+            usedPercent: percent,
+            remainingPercent: leftPercent(percent),
+            windowMinutes,
+            resetsAt,
+            status: statusFor(percent),
+            source: 'headers'
+        }, observedAt));
+    }
+    // The common x-ratelimit-* headers.
+    const families = new Map();
+    for (const [key, value] of headers) {
+        const match = /^x-ratelimit-(limit|remaining|reset)-(.+)$/.exec(key);
+        if (!match)
+            continue;
+        const bucket = families.get(match[2]) ?? {};
+        bucket[match[1]] = value;
+        families.set(match[2], bucket);
+    }
+    for (const [family, bucket] of families) {
+        if (!RATE_FAMILIES.includes(family))
+            continue;
+        const limit = toNumber(bucket.limit);
+        const remaining = toNumber(bucket.remaining);
+        const resetsAt = toIso(bucket.reset, now);
+        if (limit === null && remaining === null && !resetsAt)
+            continue;
+        const used = limit !== null && remaining !== null ? Math.max(0, limit - remaining) : null;
+        const usedPercent = limit !== null && limit > 0 && used !== null ? (used / limit) * 100 : null;
+        put(entry({
+            id: `${provider}:rate-${family}`,
+            label: `${title(family)} (rate)`,
+            provider,
+            kind: 'rate',
+            unit: family.includes('token') ? 'tokens' : 'requests',
+            used,
+            limit,
+            remaining,
+            usedPercent,
+            remainingPercent: leftPercent(usedPercent),
+            resetsAt,
+            status: statusFor(usedPercent),
+            source: 'headers'
+        }, observedAt));
+    }
+    // A 429's retry hint, when the provider sent nothing richer.
+    if (response.status === 429 && !limits.size) {
+        const retry = headers.get('retry-after');
+        // `Retry-After` is a delay in seconds or an HTTP date, not an epoch instant.
+        const resetsAt = retry && /^\d+(?:\.\d+)?$/.test(retry.trim())
+            ? new Date(now.getTime() + Number(retry) * 1_000).toISOString()
+            : toIso(retry, now);
+        if (resetsAt) {
+            put(entry({
+                id: `${provider}:retry`,
+                label: 'Rate limited',
+                provider,
+                kind: 'error',
+                unit: 'percent',
+                status: 'rejected',
+                resetsAt,
+                source: 'headers'
+            }, observedAt));
+        }
+    }
+    return { limits: [...limits.values()] };
+}
+/** Only the limit-bearing headers, bounded, so a child process never relays an entire response. */
+export function limitHeaders(input) {
+    const kept = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(input)) {
+        const name = key.toLowerCase();
+        if (!/^(anthropic-ratelimit-|x-codex-|x-ratelimit-|retry-after$)/.test(name))
+            continue;
+        if (typeof value !== 'string' || !value.trim())
+            continue;
+        kept[name] = value.trim().slice(0, 200);
+        if (++count >= 40)
+            break;
+    }
+    return kept;
+}

package/dist/sdk/usage/limits/service.d.ts

@@ -0,0 +1,30 @@
+import type { Accounts } from "../../accounts/accounts.js";
+import { type Limit } from "../../accounts/store.js";
+import type { FetchLike, LimitReadout, ProviderResponseLike, UsageLimitsReport } from "./types.js";
+export interface UsageLimitsOptions {
+    accounts: Accounts;
+    root: () => string | null;
+    fetch?: FetchLike;
+    now?: () => Date;
+}
+export declare class UsageLimits {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly headerWrites;
+    constructor(options: UsageLimitsOptions);
+    /** Lets an account's model runtime report response headers without changing any request. */
+    observeModels(models: unknown, accountId: string): void;
+    /** Records what one provider response said. Throttled per account and provider. */
+    recordHeaders(accountId: string, provider: string, response: ProviderResponseLike): void;
+    /** What the accounts already know, without touching the network. */
+    read(accountId?: string | null): UsageLimitsReport;
+    /** Reads every provider that is due, then returns the stored report. */
+    refresh(accountId?: string | null, options?: {
+        force?: boolean;
+    }): Promise<UsageLimitsReport>;
+    private refreshProvider;
+    /** Limits known for one account and provider, for diagnostics. */
+    limitsOf(accountId: string, provider: string): Limit[];
+}
+export type { LimitReadout };

package/dist/sdk/usage/limits/service.js

@@ -0,0 +1,176 @@
+import { scrub } from "../../accounts/store.js";
+import { readUsageSettings } from "../settings.js";
+import { adapterFor } from "./adapters.js";
+import { observeProviderResponses } from "./capture.js";
+import { normalizeHeaders } from "./normalize.js";
+const DEFAULT_BASE = {
+    openrouter: 'https://openrouter.ai',
+    deepseek: 'https://api.deepseek.com',
+    anthropic: 'https://api.anthropic.com',
+    'openai-codex': 'https://chatgpt.com/backend-api',
+    'opencode-go': 'https://opencode.ai'
+};
+const HEADER_WRITE_INTERVAL_MS = 15_000;
+const REQUEST_TIMEOUT_MS = 6_000;
+function origin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+export class UsageLimits {
+    options;
+    fetchImpl;
+    now;
+    headerWrites = new Map();
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetch ?? ((url, init) => fetch(url, init));
+        this.now = options.now ?? (() => new Date());
+    }
+    /** Lets an account's model runtime report response headers without changing any request. */
+    observeModels(models, accountId) {
+        observeProviderResponses(models, (provider, response) => this.recordHeaders(accountId, provider, response));
+    }
+    /** Records what one provider response said. Throttled per account and provider. */
+    recordHeaders(accountId, provider, response) {
+        if (!provider || provider.length > 64)
+            return;
+        const key = `${accountId}\u0000${provider}`;
+        const at = this.now().getTime();
+        const last = this.headerWrites.get(key) ?? 0;
+        if (at - last < HEADER_WRITE_INTERVAL_MS)
+            return;
+        const normalized = normalizeHeaders(provider, response, this.now());
+        if (!normalized.limits.length)
+            return;
+        this.headerWrites.set(key, at);
+        try {
+            this.options.accounts.applyLimits(accountId, [{
+                    provider,
+                    limits: normalized.limits,
+                    source: 'headers',
+                    reason: null,
+                    observedAt: this.now().toISOString()
+                }]);
+        }
+        catch {
+            // The account may have been removed while a response was arriving.
+        }
+    }
+    /** What the accounts already know, without touching the network. */
+    read(accountId) {
+        const overview = this.options.accounts.overview();
+        const accounts = overview.accounts.filter((account) => !accountId || account.id === accountId);
+        return {
+            generatedAt: this.now().toISOString(),
+            accounts: accounts.map((account) => {
+                const known = new Map();
+                for (const entry of account.state.providerLimits ?? [])
+                    known.set(entry.provider, entry);
+                for (const limit of account.state.limits) {
+                    const provider = limit.provider;
+                    if (!provider || known.has(provider))
+                        continue;
+                    known.set(provider, { source: limit.source === 'provider' ? 'provider' : 'headers', reason: null, observedAt: limit.observedAt ?? this.now().toISOString() });
+                }
+                return {
+                    accountId: account.id,
+                    label: account.label,
+                    plan: account.state.plan,
+                    health: account.state.health,
+                    providers: [...known.entries()].map(([provider, entry]) => ({
+                        provider,
+                        source: entry.source,
+                        reason: entry.reason,
+                        observedAt: entry.observedAt,
+                        limits: account.state.limits.filter((limit) => limit.provider === provider && !(limit.resetsAt && Date.parse(limit.resetsAt) <= this.now().getTime()))
+                    })).sort((left, right) => left.provider.localeCompare(right.provider))
+                };
+            })
+        };
+    }
+    /** Reads every provider that is due, then returns the stored report. */
+    async refresh(accountId, options = {}) {
+        const settings = readUsageSettings(this.options.root());
+        const overview = this.options.accounts.overview();
+        const accounts = overview.accounts.filter((account) => !accountId || account.id === accountId);
+        for (const account of accounts) {
+            let credentials;
+            try {
+                credentials = await this.options.accounts.listCredentials(account.id);
+            }
+            catch {
+                continue;
+            }
+            for (const credential of credentials) {
+                const known = this.read(account.id).accounts[0]?.providers.find((entry) => entry.provider === credential.providerId);
+                const age = known ? this.now().getTime() - Date.parse(known.observedAt) : Number.POSITIVE_INFINITY;
+                if (!options.force && Number.isFinite(age) && age < settings.refreshMinutes * 60_000)
+                    continue;
+                await this.refreshProvider(this.options.accounts.find(account.id), credential.providerId, credential.type, settings.experimentalProbes);
+            }
+        }
+        return this.read(accountId);
+    }
+    async refreshProvider(account, provider, credentialType, experimental) {
+        const observedAt = this.now().toISOString();
+        const unavailable = (reason) => {
+            try {
+                this.options.accounts.applyLimits(account.id, [{ provider, limits: [], source: 'unavailable', reason: scrub(reason), observedAt }]);
+            }
+            catch {
+                // The account was removed while its limits were being read.
+            }
+        };
+        const adapter = adapterFor(provider);
+        if (!adapter)
+            return unavailable('No documented usage endpoint for this provider. Local usage is shown instead.');
+        if (adapter.stability === 'experimental' && !experimental)
+            return unavailable('Experimental provider probes are off. Turn them on in the usage plugin settings.');
+        let context;
+        try {
+            const runtime = await this.options.accounts.runtime(account);
+            const auth = await runtime.getAuth(provider);
+            if (!auth)
+                return unavailable('This provider is not signed in.');
+            const configured = runtime.getProvider(provider)?.baseUrl ?? null;
+            const expected = DEFAULT_BASE[provider];
+            if (configured && expected && origin(configured) !== origin(expected)) {
+                return unavailable('This provider uses a custom base URL, so its own usage endpoint cannot be read.');
+            }
+            context = {
+                provider,
+                credentialType,
+                auth: { ...auth.auth, ...(auth.auth.baseUrl ? {} : configured ? { baseUrl: configured } : {}) },
+                baseUrl: auth.auth.baseUrl ?? configured ?? null,
+                fetch: this.fetchImpl,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                now: this.now()
+            };
+        }
+        catch (error) {
+            return unavailable(error instanceof Error ? error.message : 'The provider credential could not be resolved.');
+        }
+        try {
+            const reading = await adapter.read(context);
+            this.options.accounts.applyLimits(account.id, [{
+                    provider,
+                    limits: reading.limits.map((limit) => ({ ...limit, provider, observedAt, source: 'provider' })),
+                    source: 'provider',
+                    reason: reading.reason ? scrub(reading.reason) : null,
+                    observedAt,
+                    plan: reading.plan ?? null
+                }]);
+        }
+        catch (error) {
+            unavailable(error instanceof Error ? error.message : 'The provider usage endpoint could not be read.');
+        }
+    }
+    /** Limits known for one account and provider, for diagnostics. */
+    limitsOf(accountId, provider) {
+        return this.options.accounts.overview().accounts.find((account) => account.id === accountId)?.state.limits.filter((limit) => limit.provider === provider) ?? [];
+    }
+}

package/dist/sdk/usage/limits/types.d.ts

@@ -0,0 +1,65 @@
+import type { Limit } from "../../accounts/store.js";
+export interface ProviderResponseLike {
+    status: number;
+    headers: Record<string, string>;
+}
+/** The credential Pi resolved for this provider: an API key, request headers, or both. */
+export interface LimitAuth {
+    apiKey?: string;
+    headers?: Record<string, string | null>;
+    baseUrl?: string;
+}
+export interface LimitReadout {
+    provider: string;
+    limits: Limit[];
+    source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+    reason: string | null;
+    observedAt: string;
+    plan?: string | null;
+}
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    redirect?: 'error' | 'follow' | 'manual';
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface AdapterContext {
+    provider: string;
+    credentialType: 'api_key' | 'oauth';
+    auth: LimitAuth;
+    /** The provider's base URL, reflected from a `models.json` override when one exists. */
+    baseUrl: string | null;
+    fetch: FetchLike;
+    signal: AbortSignal;
+    now: Date;
+}
+export interface AdapterReading {
+    limits: Limit[];
+    plan?: string | null;
+    reason?: string | null;
+}
+export interface ProviderLimitAdapter {
+    id: string;
+    providers: readonly string[];
+    /** `documented` reads the provider's own usage API; `experimental` is off until a person allows it. */
+    stability: 'documented' | 'experimental';
+    read(context: AdapterContext): Promise<AdapterReading>;
+}
+export interface UsageLimitsReport {
+    generatedAt: string;
+    accounts: {
+        accountId: string;
+        label: string;
+        plan: string | null;
+        health: string;
+        providers: {
+            provider: string;
+            source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+            reason: string | null;
+            observedAt: string;
+            limits: Limit[];
+        }[];
+    }[];
+}

package/dist/sdk/usage/limits/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sdk/usage/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function usageServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/usage/serverMethods.js

@@ -0,0 +1,22 @@
+const text = (params, name) => typeof params[name] === 'string' && params[name] ? params[name] : undefined;
+const scopeOf = (value) => value === 'session' || value === 'account' || value === 'project' || value === 'all' ? value : undefined;
+const periodOf = (value) => value === 'today' || value === '7d' || value === '30d' || value === 'all' ? value : undefined;
+export function usageServerMethods(harness) {
+    return {
+        'usage.summary': (params) => harness.usage.summary({
+            scope: scopeOf(params.scope),
+            sessionId: text(params, 'sessionId'),
+            accountId: text(params, 'accountId'),
+            projectId: text(params, 'projectId'),
+            period: periodOf(params.period),
+            ...(typeof params.timezoneOffsetMinutes === 'number' ? { timezoneOffsetMinutes: params.timezoneOffsetMinutes } : {})
+        }),
+        'usage.limits': async (params) => {
+            const accountId = text(params, 'accountId');
+            return params.refresh === true
+                ? harness.usageLimits.refresh(accountId ?? null, { force: true })
+                : harness.usageLimits.read(accountId ?? null);
+        },
+        'usage.sync': () => harness.usage.sync()
+    };
+}

package/dist/sdk/usage/service.d.ts

@@ -0,0 +1,32 @@
+import type { Accounts } from "../accounts/accounts.js";
+import { type RatesLookup } from "./analytics.js";
+import { type UsagePeriod, type UsageScope, type UsageSummary } from "./types.js";
+export interface UsageOptions {
+    root: () => string;
+    accounts: Accounts;
+    rates?: RatesLookup;
+    now?: () => Date;
+}
+export interface UsageSummaryInput {
+    scope?: UsageScope | null;
+    sessionId?: string | null;
+    accountId?: string | null;
+    projectId?: string | null;
+    period?: UsagePeriod | null;
+    timezoneOffsetMinutes?: number | null;
+}
+export declare class Usage {
+    private readonly options;
+    private readonly now;
+    private readonly rates;
+    constructor(options: UsageOptions);
+    /** The one question the analysis page asks. */
+    summary(input: UsageSummaryInput): Promise<UsageSummary>;
+    /** Indexes runs the ledger has not seen, such as runs recorded by an earlier process. */
+    sync(): {
+        runs: number;
+        indexed: number;
+        lastIndexedAt: string | null;
+    };
+    private filter;
+}

package/dist/sdk/usage/service.js

@@ -0,0 +1,66 @@
+import { invalid } from "../core/errors.js";
+import { summarize } from "./analytics.js";
+import { indexedRuns, lastIndexedAt, syncUsage } from "./ledger.js";
+import { modelRates } from "../sessions/pricing.js";
+import { USAGE_PERIODS } from "./types.js";
+export class Usage {
+    options;
+    now;
+    rates;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        // List rates only price a request the provider did not price; a failed lookup leaves it unknown.
+        this.rates = options.rates ?? ((provider, model) => modelRates(provider, model));
+    }
+    /** The one question the analysis page asks. */
+    async summary(input) {
+        const root = this.options.root();
+        // A data root that has never been indexed gets one bounded catch-up pass on first use.
+        if (!lastIndexedAt(root))
+            syncUsage(root);
+        const period = input.period && USAGE_PERIODS.includes(input.period) ? input.period : '7d';
+        const scope = input.scope === 'session' || input.scope === 'project' || input.scope === 'all' || input.scope === 'account'
+            ? input.scope
+            : input.sessionId ? 'session' : input.projectId ? 'project' : input.accountId ? 'account' : 'all';
+        const filter = this.filter(scope, input);
+        const labels = new Map(this.options.accounts.overview().accounts.map((account) => [account.id, account.label]));
+        return summarize({
+            root,
+            filter,
+            period,
+            timezoneOffsetMinutes: typeof input.timezoneOffsetMinutes === 'number' ? input.timezoneOffsetMinutes : 0,
+            accountLabel: (id) => labels.get(id) ?? id.slice(0, 8),
+            rates: this.rates,
+            now: this.now()
+        });
+    }
+    /** Indexes runs the ledger has not seen, such as runs recorded by an earlier process. */
+    sync() {
+        const root = this.options.root();
+        const runs = syncUsage(root);
+        return { runs, indexed: indexedRuns(root).length, lastIndexedAt: lastIndexedAt(root) };
+    }
+    filter(scope, input) {
+        const overview = this.options.accounts.overview();
+        const defaultAccount = overview.defaults.pi ?? overview.accounts[0]?.id ?? null;
+        switch (scope) {
+            case 'session':
+                if (!input.sessionId)
+                    throw invalid('A session id is required for session usage.');
+                return { session: input.sessionId, account: null, project: null };
+            case 'project':
+                if (!input.projectId)
+                    throw invalid('A project id is required for project usage.');
+                return { session: null, account: null, project: input.projectId };
+            case 'account': {
+                const accountId = input.accountId ?? defaultAccount;
+                if (!accountId)
+                    throw invalid('An account is required for account usage.');
+                return { session: null, account: accountId, project: null };
+            }
+            default:
+                return { session: null, account: null, project: null };
+        }
+    }
+}

package/dist/sdk/usage/settings.d.ts

@@ -0,0 +1,7 @@
+import type { PluginSetting } from "../plugins/types.js";
+export declare const USAGE_SETTINGS: readonly PluginSetting[];
+export interface UsageSettings {
+    refreshMinutes: number;
+    experimentalProbes: boolean;
+}
+export declare function readUsageSettings(root: string | null): UsageSettings;

package/dist/sdk/usage/settings.js

@@ -0,0 +1,28 @@
+import { settingValue } from "../plugins/firstParty.js";
+import * as attachments from "../plugins/attachments.js";
+export const USAGE_SETTINGS = [
+    {
+        key: 'refreshMinutes',
+        label: 'Limit refresh interval',
+        description: 'How long a provider limit reading is kept before opening /usage:limit asks the provider again.',
+        default: 10,
+        min: 1,
+        max: 240
+    },
+    {
+        key: 'experimentalProbes',
+        label: 'Experimental provider probes',
+        description: 'Allow undocumented provider usage endpoints. Off by default; they can change without notice.',
+        default: 0,
+        min: 0,
+        max: 1
+    }
+];
+export function readUsageSettings(root) {
+    const saved = root ? attachments.load(root).settings.usage : undefined;
+    const values = Object.fromEntries(USAGE_SETTINGS.map((setting) => [setting.key, settingValue(setting, saved)]));
+    return {
+        refreshMinutes: values.refreshMinutes ?? 10,
+        experimentalProbes: (values.experimentalProbes ?? 0) === 1
+    };
+}