ftown 0.25.2 → 0.25.3

package/dist/quota/routing.js

@@ -0,0 +1,180 @@
+import { formatDuration } from './format.js';
+import { QUOTA_PROVIDER_IDS } from './types.js';
+const MINUTE_MS = 60_000;
+const IMMINENT_RESET_MINUTES = 10;
+const RUNWAY_LOW = 0.5;
+const RUNWAY_CAP = 99;
+/** Higher = more binding (worse for routing). unknown never binds. */
+const SEVERITY = {
+    available: 0,
+    low: 1,
+    exhausted: 2,
+    unknown: -1,
+};
+/** Sort rank for routing advice, best first. */
+const RANK = {
+    available: 0,
+    low: 1,
+    unknown: 2,
+    exhausted: 3,
+};
+const KIND_ORDER = {
+    five_hour: 0,
+    weekly: 1,
+};
+const LABEL = {
+    five_hour: '5-hour',
+    weekly: 'weekly',
+};
+/** Assesses one window against `now`. Pure: never reads the clock. */
+export function assessWindow(window, now) {
+    const used = window.usedPercent;
+    const measuredLeft = used !== null && Number.isFinite(used)
+        ? Math.round(Math.min(100, Math.max(0, 100 - used)))
+        : null;
+    const resetMs = window.resetsAt !== null ? Date.parse(window.resetsAt) : Number.NaN;
+    const resetsInMinutes = Number.isNaN(resetMs)
+        ? null
+        : Math.max(0, Math.floor((resetMs - now.getTime()) / MINUTE_MS));
+    if (measuredLeft !== null &&
+        resetsInMinutes !== null &&
+        resetsInMinutes <= IMMINENT_RESET_MINUTES) {
+        // About to reset: the current figure is irrelevant, so it counts as fully available.
+        return {
+            availability: 'available',
+            leftPercent: 100,
+            resetsInMinutes,
+            runway: null,
+            resetting: true,
+        };
+    }
+    const windowMinutes = window.windowMinutes;
+    let runway = null;
+    if (measuredLeft !== null &&
+        windowMinutes !== null &&
+        Number.isFinite(windowMinutes) &&
+        windowMinutes > 0 &&
+        resetsInMinutes !== null &&
+        resetsInMinutes > 0) {
+        const raw = (measuredLeft / 100) / (resetsInMinutes / windowMinutes);
+        runway = Math.min(RUNWAY_CAP, Math.round(raw * 100) / 100);
+    }
+    let availability;
+    if (measuredLeft === null) {
+        availability = 'unknown';
+    }
+    else if (measuredLeft <= 1) {
+        availability = 'exhausted';
+    }
+    else if (measuredLeft < 15) {
+        availability = 'low';
+    }
+    else if (runway !== null && runway < RUNWAY_LOW) {
+        availability = 'low';
+    }
+    else {
+        availability = 'available';
+    }
+    return {
+        availability,
+        leftPercent: measuredLeft,
+        resetsInMinutes,
+        runway,
+        resetting: false,
+    };
+}
+/** True when `a` should bind over `b`: worse availability, then less left, then kind order. */
+function isMoreBinding(a, b) {
+    const severityA = SEVERITY[a.availability];
+    const severityB = SEVERITY[b.availability];
+    if (severityA !== severityB)
+        return severityA > severityB;
+    if (a.leftPercent !== b.leftPercent)
+        return a.leftPercent < b.leftPercent;
+    return KIND_ORDER[a.window.kind] < KIND_ORDER[b.window.kind];
+}
+function unknownRouting(row) {
+    const message = row.message?.trim() ?? '';
+    return {
+        provider: row.provider,
+        availability: 'unknown',
+        leftPercent: null,
+        bindingWindow: null,
+        resetsAt: null,
+        resetsInMinutes: null,
+        runway: null,
+        reason: message.length > 0 ? message : 'no usage numbers available',
+    };
+}
+function reasonFor(binding) {
+    const label = LABEL[binding.window.kind];
+    const left = binding.leftPercent;
+    const duration = binding.resetsInMinutes !== null
+        ? formatDuration(binding.resetsInMinutes * MINUTE_MS)
+        : null;
+    const resetClause = duration !== null ? `, resets in ${duration}` : '';
+    const runwayClause = binding.runway !== null && binding.runway > 0 ? ` (runway ${binding.runway}x)` : '';
+    if (binding.resetting) {
+        return duration !== null
+            ? `${label} window resets in ${duration}`
+            : `${label} window resets soon`;
+    }
+    if (binding.availability === 'exhausted') {
+        return `${label} window used up${resetClause}`;
+    }
+    if (binding.availability === 'low' && left < 15) {
+        return `only ${left}% of the ${label} window left${resetClause}${runwayClause}`;
+    }
+    if (binding.availability === 'low') {
+        const untilReset = duration !== null ? ` but ${duration} until reset` : '';
+        return `${left}% of the ${label} window left${untilReset}${runwayClause}`;
+    }
+    return `${left}% of the ${label} window left${resetClause}${runwayClause}`;
+}
+function adviseRow(row, now) {
+    const usable = [];
+    for (const window of row.windows) {
+        const assessed = assessWindow(window, now);
+        if (assessed.availability !== 'unknown' && assessed.leftPercent !== null) {
+            usable.push({
+                window,
+                availability: assessed.availability,
+                leftPercent: assessed.leftPercent,
+                resetsInMinutes: assessed.resetsInMinutes,
+                runway: assessed.runway,
+                resetting: assessed.resetting,
+            });
+        }
+    }
+    if (row.status !== 'ok' || usable.length === 0) {
+        return unknownRouting(row);
+    }
+    const binding = usable.reduce((best, candidate) => isMoreBinding(candidate, best) ? candidate : best);
+    return {
+        provider: row.provider,
+        availability: binding.availability,
+        leftPercent: binding.leftPercent,
+        bindingWindow: binding.window.kind,
+        resetsAt: binding.window.resetsAt,
+        resetsInMinutes: binding.resetsInMinutes,
+        runway: binding.resetting ? null : binding.runway,
+        reason: reasonFor(binding),
+    };
+}
+/** Quota left scaled by pace: 0% left always scores 0; null left scores -1. */
+function score(advice) {
+    if (advice.leftPercent === null)
+        return -1;
+    return (advice.leftPercent / 100) * Math.min(1, advice.runway ?? 1);
+}
+function compareRouting(a, b) {
+    const rankDiff = RANK[a.availability] - RANK[b.availability];
+    if (rankDiff !== 0)
+        return rankDiff;
+    const scoreDiff = score(b) - score(a);
+    if (scoreDiff !== 0)
+        return scoreDiff;
+    return QUOTA_PROVIDER_IDS.indexOf(a.provider) - QUOTA_PROVIDER_IDS.indexOf(b.provider);
+}
+export const adviseQuotaRouting = (rows, now) => rows.map((row) => adviseRow(row, now)).sort(compareRouting);
+//# sourceMappingURL=routing.js.map

package/dist/quota/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/quota/routing.ts"],"names":[],"mappings":"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"}

package/dist/quota/types.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Frozen contract for the subscription-quota tool (`ftown-quota`).
+ *
+ * "Quota" here means SUBSCRIPTION PLAN limits (the short ~5-hour window and
+ * the weekly window), not per-session token counts (see usage-collector.ts).
+ *
+ * This file is types only. Do not add logic and do not edit it from a task.
+ */
+export type QuotaProviderId = 'claude' | 'codex' | 'grok' | 'muse' | 'agy' | 'opencode';
+export declare const QUOTA_PROVIDER_IDS: readonly QuotaProviderId[];
+/**
+ * `five_hour` is the provider's short rolling block (its real length is in
+ * `windowMinutes` when the provider states it). `weekly` is the 7-day block.
+ */
+export type QuotaWindowKind = 'five_hour' | 'weekly';
+export interface QuotaWindow {
+    kind: QuotaWindowKind;
+    /**
+     * Percent of the window already used, 0-100 scale (may exceed 100).
+     * null when the provider reports the window but no number for it.
+     */
+    usedPercent: number | null;
+    /** ISO-8601 UTC instant the window resets, or null when unknown. */
+    resetsAt: string | null;
+    /** Window length in minutes as stated by the provider, or null. */
+    windowMinutes: number | null;
+    /** Short human note for this window (e.g. "no active window"), or null. */
+    note: string | null;
+}
+/**
+ * ok          - at least one window with data.
+ * no_data     - provider reachable but it reported no allowance right now.
+ * auth        - credentials missing or expired; `message` says how to fix.
+ * unavailable - the provider has no usable source on this machine right now.
+ * error       - unexpected failure; `message` carries a short reason.
+ */
+export type QuotaStatus = 'ok' | 'no_data' | 'auth' | 'unavailable' | 'error';
+export interface ProviderQuota {
+    provider: QuotaProviderId;
+    status: QuotaStatus;
+    /** Plan / tier name as reported by the provider, or null. */
+    plan: string | null;
+    /**
+     * Only windows the provider actually reported. A kind missing from this
+     * array means the provider did not report that window (for example the
+     * plan has no 5-hour window). At most one entry per kind.
+     */
+    windows: QuotaWindow[];
+    /** live = asked the provider just now; cached = read from a local file. */
+    source: 'live' | 'cached';
+    /** ISO-8601 UTC instant the numbers were observed by the provider/file. */
+    observedAt: string;
+    /** Short single-line explanation for any non-ok status, else null. */
+    message: string | null;
+    /**
+     * Extra limits that apply to only part of the plan (for example a weekly
+     * limit for one model family). Omitted or empty when the provider reports none.
+     */
+    scopedLimits?: ScopedLimit[];
+}
+/** A limit that applies to a subset of the plan, e.g. one model family. */
+export interface ScopedLimit {
+    /** What the limit applies to, as the provider names it (e.g. "Fable"). */
+    scope: string;
+    kind: QuotaWindowKind;
+    /** Percent used, 0-100 scale, or null when not reported. */
+    usedPercent: number | null;
+    /** ISO-8601 UTC reset instant, or null. */
+    resetsAt: string | null;
+}
+export interface QuotaFetchOptions {
+    /** Hard cap for the whole fetch of one provider, in milliseconds. */
+    timeoutMs: number;
+    /** Clock, injectable for tests. */
+    now: () => Date;
+    /** Home directory to resolve provider state under (os.homedir() in prod). */
+    homeDir: string;
+}
+/**
+ * Every provider module exports one of these. It MUST NOT throw or reject:
+ * any failure becomes a ProviderQuota with a non-ok status. It MUST NOT
+ * print anything, and MUST NOT include secrets in `message`.
+ */
+export type QuotaFetcher = (options: QuotaFetchOptions) => Promise<ProviderQuota>;
+/** Signature of the table renderer in format.ts. Returns text without a trailing newline. */
+export type QuotaTableFormatter = (rows: readonly ProviderQuota[], now: Date) => string;
+/**
+ * available - enough quota left for normal work.
+ * low       - usable, but close to its limit or burning faster than the window allows.
+ * exhausted - effectively no quota left until the window resets.
+ * unknown   - no usable numbers (provider status not ok, or no numeric window).
+ */
+export type QuotaAvailability = 'available' | 'low' | 'exhausted' | 'unknown';
+export interface ProviderRouting {
+    provider: QuotaProviderId;
+    availability: QuotaAvailability;
+    /**
+     * Percent LEFT (0-100) in the binding window: the window with the least
+     * left among those that have a number. null when unknown.
+     */
+    leftPercent: number | null;
+    /** Which window is the binding one, or null when unknown. */
+    bindingWindow: QuotaWindowKind | null;
+    /** When the binding window resets (ISO-8601 UTC), or null. */
+    resetsAt: string | null;
+    /** Whole minutes until the binding window resets (>= 0), or null. */
+    resetsInMinutes: number | null;
+    /**
+     * Quota left relative to time left in the binding window:
+     * (leftPercent / 100) / (minutes until reset / windowMinutes).
+     * 1 = exactly on pace, > 1 = spare capacity, < 1 = will run out before the
+     * reset at an even pace. null when the window length or reset is unknown.
+     */
+    runway: number | null;
+    /** One short sentence an agent can read to understand the verdict. */
+    reason: string;
+}
+/** The `--json` output of ftown-quota. */
+export interface QuotaReport {
+    /** ISO-8601 UTC instant the report was produced. */
+    generatedAt: string;
+    /** Raw per-provider readings, in canonical provider order. */
+    providers: ProviderQuota[];
+    /** Routing advice, best provider to use FIRST. Same providers as above. */
+    routing: ProviderRouting[];
+    /** Models each provider offers, in canonical provider order. */
+    models: ProviderModels[];
+    /** State of the user's model-routing file on this machine. */
+    routingConfig: RoutingConfigState;
+    /** The user's tiers, each pick annotated with live availability. Empty unless routingConfig.status is "ok". */
+    tiers: AnnotatedTier[];
+    /** The user's free-text guidance for the router agent, passed through verbatim ("" when none). */
+    steering: string;
+}
+/** Signature of the advisor in routing.ts. Returns advice sorted best-first. */
+export type QuotaRoutingAdvisor = (rows: readonly ProviderQuota[], now: Date) => ProviderRouting[];
+/**
+ * What a model costs the logged-in account. free = zero-priced on a
+ * pay-per-use provider; included = covered by a subscription plan the user
+ * holds; paid = billed per use.
+ */
+export type ModelPricing = 'free' | 'included' | 'paid';
+export interface HarnessModel {
+    /** Exact value to pass to the harness's model flag. */
+    id: string;
+    /** Human display name, or null. */
+    name: string | null;
+    /** True for the model a new session uses when no model flag is given. */
+    isDefault: boolean;
+    /** Provider's own one-line description, or null. */
+    description: string | null;
+    /** Largest context window in tokens the provider states, or null. */
+    contextTokens: number | null;
+    /** Reasoning-effort levels the model supports, in the provider's order. Empty when none/unknown. */
+    efforts: string[];
+    /** Effort used when none is given, or null when unknown. */
+    defaultEffort: string | null;
+    /** Cost class when the harness states prices; omitted when unknown or not applicable. */
+    pricing?: ModelPricing;
+}
+export interface ProviderModels {
+    provider: QuotaProviderId;
+    /** ok = list read; unavailable = no source on this machine; error = unexpected failure. */
+    status: 'ok' | 'unavailable' | 'error';
+    /** Models a user can select (hidden/internal ones excluded). Empty unless status is ok. */
+    models: HarnessModel[];
+    /** live = asked the harness just now; cached = read from a file the harness maintains. */
+    source: 'live' | 'cached';
+    /** ISO-8601 UTC instant the list was produced or last refreshed by the harness. */
+    observedAt: string;
+    /** Short single-line explanation for any non-ok status, else null. */
+    message: string | null;
+    /** How to select a model when launching the harness, e.g. "--model <id>". */
+    modelFlag: string;
+    /** How to select a reasoning effort when launching, e.g. "--effort <level>", or null. */
+    effortFlag: string | null;
+}
+/**
+ * Every models module exports one of these. Same rules as QuotaFetcher:
+ * never throw or reject, never print, no secrets in `message`, never start
+ * a model turn.
+ */
+export type ModelsFetcher = (options: QuotaFetchOptions) => Promise<ProviderModels>;
+/** Location of the routing file, relative to the home directory. */
+export declare const MODEL_ROUTING_RELATIVE_PATH = ".ftown/model-routing.json";
+/** Limits enforced when validating a routing config. */
+export declare const MODEL_ROUTING_LIMITS: {
+    readonly maxTiers: 12;
+    readonly maxPicksPerTier: 12;
+    readonly maxTierNameLength: 40;
+    readonly maxTierDescriptionLength: 200;
+    readonly maxTierGuidanceLength: 1000;
+    readonly maxSteeringLength: 4000;
+};
+/** Tier names are lowercase slugs so a router agent can refer to them unambiguously. */
+export declare const ROUTING_TIER_NAME_PATTERN: RegExp;
+export interface RoutingPick {
+    /** Harness CLI. */
+    provider: QuotaProviderId;
+    /** Model id exactly as that harness's model list gives it. */
+    model: string;
+    /** Reasoning effort to request, or null to use the harness default. */
+    effort: string | null;
+}
+export interface RoutingTier {
+    /** Unique within the config; matches ROUTING_TIER_NAME_PATTERN. */
+    name: string;
+    /** What kind of work belongs in this tier, in the user's words ("" when none). */
+    description: string;
+    /** Preferred entries, most preferred first. May be empty. */
+    picks: RoutingPick[];
+    /**
+     * Free-text instruction for this tier, interpreted by the router agent and
+     * never by the tool, e.g. "otherwise any free opencode model" ("" when none).
+     */
+    guidance: string;
+}
+export interface ModelRoutingConfig {
+    version: 1;
+    /** In the user's order. */
+    tiers: RoutingTier[];
+    /** Free-text guidance for the router agent, e.g. "don't fully exhaust Claude". */
+    steering: string;
+}
+/** The tiers offered when no routing file exists yet. Picks start empty: the user fills them in. */
+export declare const DEFAULT_ROUTING_TIERS: readonly Readonly<Pick<RoutingTier, 'name' | 'description'>>[];
+export interface RoutingConfigState {
+    /** ok = loaded; missing = no file yet; invalid = the file has errors. */
+    status: 'ok' | 'missing' | 'invalid';
+    /** Absolute path of the routing file. */
+    path: string;
+    /** Validation errors when invalid, else []. */
+    errors: string[];
+}
+/** Result of validating a routing config document. Never a partially valid config. */
+export type RoutingConfigParseResult = {
+    ok: true;
+    config: ModelRoutingConfig;
+} | {
+    ok: false;
+    errors: string[];
+};
+export interface AnnotatedPick extends RoutingPick {
+    /** Display name of the model from the live list, or null. */
+    modelName: string | null;
+    /** The provider's current availability (from the routing advice). */
+    availability: QuotaAvailability;
+    /** Percent left in the provider's binding window, or null. */
+    leftPercent: number | null;
+    /** When that binding window resets (ISO-8601 UTC), or null. */
+    resetsAt: string | null;
+    /** The provider's partial limits (e.g. per model family), for the router to weigh. */
+    scopedLimits: ScopedLimit[];
+    /**
+     * Non-null when the pick cannot be used as configured: the model is no
+     * longer offered by the harness, or the effort is not one it supports.
+     * Null when the pick is valid or could not be checked (no model list).
+     */
+    problem: string | null;
+    /** false when the harness's model list could not be read, so the pick was not checked. */
+    checked: boolean;
+}
+export interface AnnotatedTier {
+    name: string;
+    description: string;
+    /** In the user's order of preference. */
+    picks: AnnotatedPick[];
+    /** The tier's free-text guidance, verbatim. */
+    guidance: string;
+}
+export declare const MODEL_ROUTING_SCHEMA = 1;
+/** A `refresh: true` request arriving sooner than this after the last collection is served from cache. */
+export declare const MODEL_ROUTING_MIN_REFRESH_MS = 15000;
+/** Payload of the `get_model_routing` command. */
+export interface GetModelRoutingPayload {
+    /** true = bypass the bridge's cache and read quota and model lists again. */
+    refresh?: boolean;
+}
+/** Result of `get_model_routing`. */
+export interface ModelRoutingSnapshot {
+    schema: 1;
+    /** The stored config, or a starter config (default tiers, no picks, no steering) when none is stored or it is invalid. */
+    config: ModelRoutingConfig;
+    /** Full report: quota, routing advice, model lists, and the annotated tiers. */
+    report: QuotaReport;
+    /** true when the quota/model part of `report` came from the bridge's cache. */
+    cached: boolean;
+}
+/** Payload of the `set_model_routing` command. */
+export interface SetModelRoutingPayload {
+    config: ModelRoutingConfig;
+    /** Must be true to replace a routing file that exists but is invalid. */
+    overwriteInvalid?: boolean;
+}
+/** Result of `set_model_routing`. */
+export interface SetModelRoutingResult {
+    schema: 1;
+    /** false when validation failed; nothing was written. */
+    saved: boolean;
+    /** Validation errors, each a short sentence naming the offending field; [] when saved. */
+    errors: string[];
+    /** true when nothing was written because the existing file is invalid and overwriteInvalid was not set. */
+    invalidFileBlocked?: boolean;
+}

package/dist/quota/types.js

@@ -0,0 +1,45 @@
+/**
+ * Frozen contract for the subscription-quota tool (`ftown-quota`).
+ *
+ * "Quota" here means SUBSCRIPTION PLAN limits (the short ~5-hour window and
+ * the weekly window), not per-session token counts (see usage-collector.ts).
+ *
+ * This file is types only. Do not add logic and do not edit it from a task.
+ */
+export const QUOTA_PROVIDER_IDS = ['claude', 'codex', 'grok', 'muse', 'agy', 'opencode'];
+// ---------------------------------------------------------------------------
+// Model routing: the user's own tiers. For each tier the user picks, in order
+// of preference, concrete (harness CLI + model + effort) entries on a
+// per-bridge screen in the dashboard, plus free-text steering. The tool never
+// ranks models itself and never chooses: it joins the picks with live quota so
+// that a ROUTER AGENT can choose the CLI, model and effort for a given task.
+// Stored on the bridge machine; one file per machine.
+// ---------------------------------------------------------------------------
+/** Location of the routing file, relative to the home directory. */
+export const MODEL_ROUTING_RELATIVE_PATH = '.ftown/model-routing.json';
+/** Limits enforced when validating a routing config. */
+export const MODEL_ROUTING_LIMITS = {
+    maxTiers: 12,
+    maxPicksPerTier: 12,
+    maxTierNameLength: 40,
+    maxTierDescriptionLength: 200,
+    maxTierGuidanceLength: 1000,
+    maxSteeringLength: 4000,
+};
+/** Tier names are lowercase slugs so a router agent can refer to them unambiguously. */
+export const ROUTING_TIER_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+/** The tiers offered when no routing file exists yet. Picks start empty: the user fills them in. */
+export const DEFAULT_ROUTING_TIERS = [
+    { name: 'advisory', description: 'Planning, architecture, review and second opinions' },
+    { name: 'complex', description: 'Hard development and debugging' },
+    { name: 'moderate', description: 'Ordinary development tasks' },
+    { name: 'simple', description: 'Research, lookups and mechanical edits' },
+];
+// ---------------------------------------------------------------------------
+// Dashboard <-> bridge protocol for model routing (bridge command RPC).
+// The dashboard imports these types from this file directly; do not copy them.
+// ---------------------------------------------------------------------------
+export const MODEL_ROUTING_SCHEMA = 1;
+/** A `refresh: true` request arriving sooner than this after the last collection is served from cache. */
+export const MODEL_ROUTING_MIN_REFRESH_MS = 15_000;
+//# sourceMappingURL=types.js.map

package/dist/quota/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/quota/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAA+B,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AAwMrH,8EAA8E;AAC9E,8EAA8E;AAC9E,sEAAsE;AACtE,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,sDAAsD;AACtD,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAA2B,CAAC;AAEvE,wDAAwD;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,QAAQ,EAAE,EAAE;IACZ,eAAe,EAAE,EAAE;IACnB,iBAAiB,EAAE,EAAE;IACrB,wBAAwB,EAAE,GAAG;IAC7B,qBAAqB,EAAE,IAAI;IAC3B,iBAAiB,EAAE,IAAI;CACf,CAAC;AAEX,wFAAwF;AACxF,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAiCjE,oGAAoG;AACpG,MAAM,CAAC,MAAM,qBAAqB,GAAmE;IACnG,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,oDAAoD,EAAE;IACvF,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,gCAAgC,EAAE;IAClE,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,4BAA4B,EAAE;IAC/D,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wCAAwC,EAAE;CAC1E,CAAC;AA8CF,8EAA8E;AAC9E,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAE9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,0GAA0G;AAC1G,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC"}

package/dist/quota-cli.d.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { type AnnotatedTier, type ModelRoutingConfig, type ModelsFetcher, type ProviderModels, type ProviderQuota, type ProviderRouting, type QuotaFetcher, type QuotaProviderId, type QuotaReport, type QuotaRoutingAdvisor, type QuotaTableFormatter, type RoutingConfigState } from './quota/types.js';
+export declare const QUOTA_DEFAULT_TIMEOUT_SECONDS = 15;
+/** Allowed --timeout range in seconds; keeps timeoutMs + grace well inside the timer limit. */
+export declare const QUOTA_MIN_TIMEOUT_SECONDS = 1;
+export declare const QUOTA_MAX_TIMEOUT_SECONDS = 600;
+/** Extra time past the provider timeout before the CLI gives up on a fetcher that never settles. */
+export declare const QUOTA_GRACE_MS = 2000;
+export declare const QUOTA_HELP_TEXT: string;
+/** Table mode shows at most this many models per provider; JSON is never truncated. */
+export declare const MODEL_LIST_TABLE_LIMIT = 20;
+/** `default`: models in JSON only; `show`: models in table mode too; `skip`: no model fetchers at all. */
+export type QuotaModelsMode = 'default' | 'show' | 'skip';
+export type QuotaArgs = {
+    ok: true;
+    providers: QuotaProviderId[];
+    json: boolean;
+    timeoutMs: number;
+    help: boolean;
+    models: QuotaModelsMode;
+} | {
+    ok: false;
+    error: string;
+};
+/** Reads the user's routing file; see quota/routing-config.ts. */
+export type RoutingLoader = (homeDir: string) => Promise<{
+    state: RoutingConfigState;
+    config: ModelRoutingConfig | null;
+}>;
+/** Joins the user's tiers with live quota, routing advice and model lists; see quota/annotate.ts. */
+export type TierAnnotator = (config: ModelRoutingConfig, quota: readonly ProviderQuota[], routing: readonly ProviderRouting[], models: readonly ProviderModels[]) => AnnotatedTier[];
+export interface QuotaDeps {
+    fetchers: Record<QuotaProviderId, QuotaFetcher>;
+    modelFetchers: Record<QuotaProviderId, ModelsFetcher>;
+    advise: QuotaRoutingAdvisor;
+    format: QuotaTableFormatter;
+    loadRouting: RoutingLoader;
+    annotate: TierAnnotator;
+    now: () => Date;
+    homeDir: string;
+    /** Grace past the provider timeout before a hung fetcher becomes an error entry. Default QUOTA_GRACE_MS. */
+    graceMs?: number;
+}
+export interface QuotaRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True when at least one quota or model fetcher did not settle in time and was replaced. */
+    hung: boolean;
+}
+export interface CollectQuotaInput {
+    providers: QuotaProviderId[];
+    timeoutMs: number;
+    /** Put the model lists in the report. */
+    includeModels: boolean;
+    /** Also fetch model lists when the routing config has picks, so the tiers can be checked against them. */
+    fetchModelsForRouting?: boolean;
+}
+export interface CollectedQuotaReport {
+    report: QuotaReport;
+    hung: boolean;
+    /** Short stderr lines for non-fatal problems (routing advice, routing file). */
+    warnings: string[];
+}
+export declare function parseQuotaArgs(argv: string[]): QuotaArgs;
+/**
+ * Gathers everything the report needs: guarded quota and model fetches, routing
+ * advice, and the annotated routing tiers. Never prints and never exits.
+ */
+export declare function collectQuotaReport(input: CollectQuotaInput, deps: QuotaDeps): Promise<CollectedQuotaReport>;
+export declare function runQuota(argv: string[], deps: QuotaDeps): Promise<QuotaRunResult>;
+/** The real fetchers, models, routing, formatter and clock: what the bridge passes to collectQuotaReport. */
+export declare function loadRealQuotaDeps(): Promise<QuotaDeps>;
+/**
+ * Entry for `ftown-quota` and the umbrella `ftown` CLI: runs with the real
+ * modules and writes stdout/stderr. Returns the exit code, except when a
+ * fetcher hung: then the process exits with that code after output is flushed,
+ * because a hung fetcher's handle would otherwise keep the event loop alive.
+ */
+export declare function runQuotaCli(argv: string[]): Promise<number>;