@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/services/quota-fetcher/manifest.d.ts

@@ -0,0 +1,5 @@
+import type { MutableDaemonConfig } from "@camerontaylor/paseo-protocol/messages";
+import type { ProviderUsageFetcher, ProviderUsageFetcherFactoryOptions, ProviderUsageFetcherManifestEntry } from "./provider.js";
+export declare const PROVIDER_USAGE_FETCHERS: readonly ProviderUsageFetcherManifestEntry[];
+export declare function createProviderUsageFetchers(options: ProviderUsageFetcherFactoryOptions, providers?: MutableDaemonConfig["providers"]): ProviderUsageFetcher[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/server/services/quota-fetcher/manifest.js

@@ -0,0 +1,118 @@
+import { ClaudeQuotaProvider } from "./providers/claude.js";
+import { CodexQuotaProvider } from "./providers/codex.js";
+import { CopilotQuotaProvider } from "./providers/copilot.js";
+import { CursorQuotaProvider } from "./providers/cursor.js";
+import { GrokQuotaProvider } from "./providers/grok.js";
+import { KimiQuotaProvider } from "./providers/kimi.js";
+import { MiniMaxQuotaProvider } from "./providers/minimax.js";
+import { ZaiQuotaProvider } from "./providers/zai.js";
+import { unavailableUsage } from "./usage.js";
+export const PROVIDER_USAGE_FETCHERS = [
+    {
+        providerId: "claude",
+        create: (options) => new ClaudeQuotaProvider({
+            logger: options.logger,
+            fetch: options.fetch,
+        }),
+    },
+    {
+        providerId: "codex",
+        create: (options) => new CodexQuotaProvider({
+            logger: options.logger,
+            fetch: options.fetch,
+        }),
+    },
+    {
+        providerId: "copilot",
+        create: (options) => new CopilotQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+    {
+        providerId: "cursor",
+        create: (options) => new CursorQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+    {
+        providerId: "zai",
+        create: (options) => new ZaiQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+    {
+        providerId: "grok",
+        create: (options) => new GrokQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+    {
+        providerId: "kimi",
+        create: (options) => new KimiQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+    {
+        providerId: "minimax",
+        create: (options) => new MiniMaxQuotaProvider({ logger: options.logger, fetch: options.fetch }),
+    },
+];
+export function createProviderUsageFetchers(options, providers = {}) {
+    const fetchers = [];
+    for (const entry of PROVIDER_USAGE_FETCHERS) {
+        fetchers.push(entry.create(options));
+        for (const [providerId, providerConfig] of Object.entries(providers)) {
+            if (providerConfig.extends === entry.providerId) {
+                fetchers.push(createProviderAccountUsageFetcher(options, providerId, providerConfig));
+            }
+        }
+    }
+    return fetchers;
+}
+function providerEnvironment(providerConfig) {
+    const env = providerConfig.env;
+    if (!env || typeof env !== "object" || Array.isArray(env))
+        return {};
+    return Object.fromEntries(Object.entries(env).filter((entry) => typeof entry[1] === "string"));
+}
+function createProviderAccountUsageFetcher(options, providerId, providerConfig) {
+    const baseProviderId = String(providerConfig.extends);
+    const displayName = typeof providerConfig.label === "string" && providerConfig.label.trim()
+        ? providerConfig.label.trim()
+        : providerId;
+    const env = providerEnvironment(providerConfig);
+    let baseFetcher = null;
+    if (baseProviderId === "claude") {
+        const claudeHome = env["CLAUDE_CONFIG_DIR"] || env["CLAUDE_HOME"];
+        if (claudeHome) {
+            baseFetcher = new ClaudeQuotaProvider({
+                logger: options.logger,
+                fetch: options.fetch,
+                claudeHome,
+                claudeKeychainReader: async () => null,
+            });
+        }
+    }
+    else if (baseProviderId === "codex") {
+        const codexHome = env["CODEX_HOME"];
+        if (codexHome) {
+            baseFetcher = new CodexQuotaProvider({
+                logger: options.logger,
+                fetch: options.fetch,
+                codexHome,
+                includeDefaultAuthPaths: false,
+            });
+        }
+    }
+    else if (baseProviderId === "copilot") {
+        baseFetcher = new CopilotQuotaProvider({
+            logger: options.logger,
+            fetch: options.fetch,
+            env,
+            readCliToken: async () => null,
+        });
+    }
+    return {
+        providerId,
+        baseProviderId,
+        displayName,
+        fetchUsage: async () => {
+            if (!baseFetcher) {
+                return unavailableUsage({ providerId, baseProviderId, displayName });
+            }
+            const usage = await baseFetcher.fetchUsage();
+            return { ...usage, providerId, baseProviderId, displayName };
+        },
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/server/services/quota-fetcher/provider.d.ts

@@ -0,0 +1,18 @@
+import type { Logger } from "pino";
+import type { ProviderUsage } from "../../server/messages.js";
+export type ProviderApiFetch = typeof fetch;
+export interface ProviderUsageFetcher {
+    readonly providerId: string;
+    readonly baseProviderId?: string;
+    readonly displayName: string;
+    fetchUsage(): Promise<ProviderUsage>;
+}
+export interface ProviderUsageFetcherFactoryOptions {
+    logger: Logger;
+    fetch?: ProviderApiFetch;
+}
+export interface ProviderUsageFetcherManifestEntry {
+    readonly providerId: string;
+    create(options: ProviderUsageFetcherFactoryOptions): ProviderUsageFetcher;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/server/services/quota-fetcher/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/server/services/quota-fetcher/providers/claude.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from "pino";
+import type { ProviderUsage } from "../../../server/messages.js";
+import type { ProviderApiFetch, ProviderUsageFetcher } from "../provider.js";
+interface ClaudeQuotaProviderOptions {
+    logger: Logger;
+    claudeHome?: string;
+    claudeKeychainReader?: () => Promise<unknown | null>;
+    platform?: typeof process.platform;
+    fetch?: ProviderApiFetch;
+}
+type ClaudeKeychainCommandRunner = (args: string[]) => Promise<string | null>;
+export declare function claudeKeychainAccount(user?: string): string;
+/** Read Claude Code's account-specific Keychain item, then try the legacy lookup. */
+export declare function readClaudeKeychainCredentials(run?: ClaudeKeychainCommandRunner, account?: string): Promise<unknown | null>;
+export declare class ClaudeQuotaProvider implements ProviderUsageFetcher {
+    readonly providerId = "claude";
+    readonly displayName = "Claude";
+    private readonly logger;
+    private readonly claudeHome;
+    private readonly readKeychainCredentials;
+    private readonly platform;
+    private readonly fetchApi;
+    constructor(options: ClaudeQuotaProviderOptions);
+    fetchUsage(): Promise<ProviderUsage>;
+    /**
+     * Scoped limits carried by `limits[]`.
+     *
+     * Entries are validated one at a time so a single malformed or newly-shaped entry
+     * cannot fail the whole response and take the windows that already parsed with it.
+     */
+    private scopedLimitsFromResponse;
+    private forbiddenUsage;
+    private readCredentials;
+    private readCredentialFile;
+    private readKeychainCredential;
+    private toCredentialRecord;
+    private callClaudeApi;
+}
+export {};
+//# sourceMappingURL=claude.d.ts.map

package/dist/server/services/quota-fetcher/providers/claude.js

@@ -0,0 +1,389 @@
+import { execFile } from "node:child_process";
+import { existsSync, promises as fs } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { ApiNumberSchema, fetchProviderApi, toneFromUsedPct, unavailableUsage, windowFromUsedPct, } from "../usage.js";
+const execFileAsync = promisify(execFile);
+const CLAUDE_KEYCHAIN_TIMEOUT_MS = 2000;
+const CLAUDE_OAUTH_BETA = "oauth-2025-04-20";
+const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+const ClaudeCredentialsSchema = z.object({
+    claudeAiOauth: z
+        .object({
+        accessToken: z.string().optional(),
+        refreshToken: z.string().optional(),
+        subscriptionType: z.string().optional(),
+        rateLimitTier: z.string().optional(),
+    })
+        .optional(),
+});
+const ClaudeUsageWindowSchema = z.object({
+    utilization: ApiNumberSchema,
+    resets_at: z.string().nullish(),
+});
+// Model- and surface-scoped weekly limits live in a `limits[]` array rather than a
+// top-level `seven_day_<model>` key. Entries are validated one at a time (see
+// scopedLimitsFromResponse) so a single malformed or newly-shaped entry cannot take down
+// the windows that already parsed from the top-level keys.
+const ClaudeScopeLabelSchema = z
+    .object({ id: z.string().nullish(), display_name: z.string().nullish() })
+    .nullish();
+const ClaudeLimitSchema = z.object({
+    kind: z.string(),
+    percent: ApiNumberSchema.nullish(),
+    resets_at: z.string().nullish(),
+    scope: z.object({ model: ClaudeScopeLabelSchema, surface: ClaudeScopeLabelSchema }).nullish(),
+});
+const ClaudeUsageResponseSchema = z.object({
+    five_hour: ClaudeUsageWindowSchema.nullish(),
+    seven_day: ClaudeUsageWindowSchema.nullish(),
+    seven_day_opus: ClaudeUsageWindowSchema.nullish(),
+    seven_day_omelette: ClaudeUsageWindowSchema.nullish(),
+    // Deliberately permissive: an additive section must never regress the top-level
+    // windows, so shape validation happens per entry rather than here.
+    limits: z.array(z.unknown()).nullish(),
+    extra_usage: z
+        .object({
+        is_enabled: z.boolean().optional(),
+    })
+        .nullish(),
+});
+const SCOPED_WEEKLY_KIND = "weekly_scoped";
+// A 403 is not a stale token, so refreshing cannot clear it, and refreshing anyway rewrites
+// the credentials on every poll. What causes the refusal is not visible from here, so the
+// message names the refusal rather than guessing at a reason.
+const CLAUDE_USAGE_FORBIDDEN_MESSAGE = "Usage request was refused (HTTP 403). Check the daemon's network access to api.anthropic.com.";
+function buildClaudePlan(subscriptionType, rateLimitTier) {
+    if (!subscriptionType)
+        return null;
+    const label = subscriptionType.charAt(0).toUpperCase() + subscriptionType.slice(1);
+    const tier = rateLimitTier?.split("_").pop();
+    return tier ? `${label} ${tier}` : label;
+}
+// Windows that describe no particular model or surface.
+const UNSCOPED_WINDOWS = [
+    { field: "five_hour", id: "five_hour", label: "Session" },
+    { field: "seven_day", id: "weekly", label: "Weekly" },
+];
+// Scoped windows from before `limits[]` existed. Declaring the dimension here is what
+// stops a *surface* named "Omelette" from being mistaken for the legacy Omelette *model*
+// window: these keys are model-scoped by definition.
+const LEGACY_SCOPED_WINDOWS = [
+    { field: "seven_day_opus", name: "Opus" },
+    { field: "seven_day_omelette", name: "Omelette" },
+];
+/** Fold a name down to the characters an id is allowed to carry. */
+function normalizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/**
+ * Whether two descriptions denote the same limit. This is the single definition of
+ * identity for scoped limits; nothing else may compare them, and in particular nothing
+ * may compare display labels, which are presentation rather than identity.
+ *
+ * - Different dimensions are never the same limit, so a surface and a model sharing a
+ *   name stay apart.
+ * - When both sides carry the API's own id, that id decides, so `fable-pro` and
+ *   `fable_pro` stay apart.
+ * - Otherwise fall back to the normalized name, which is the only link available between
+ *   a legacy key (never has an id) and its `limits[]` counterpart.
+ */
+function isSameLimit(a, b) {
+    if (a.dimension !== b.dimension)
+        return false;
+    if (a.id && b.id)
+        return a.id === b.id;
+    return normalizeName(a.name) === normalizeName(b.name);
+}
+/**
+ * Merge the legacy and `limits[]` descriptions into one limit per identity.
+ *
+ * A `limits[]` entry wins on identity because that is the representation the API is
+ * migrating towards, so a limit keeps the same window id whichever shape carried it.
+ * Its values are nullable though, so each field falls back to the legacy twin instead of
+ * discarding a number the response did contain.
+ */
+function reconcileScopedLimits(legacy, fromLimitsArray) {
+    const reconciled = [...legacy];
+    for (const limit of fromLimitsArray) {
+        const index = reconciled.findIndex((candidate) => isSameLimit(candidate, limit));
+        if (index === -1) {
+            reconciled.push(limit);
+            continue;
+        }
+        const twin = reconciled[index];
+        reconciled[index] = {
+            ...limit,
+            usedPct: limit.usedPct ?? twin?.usedPct ?? null,
+            resetsAt: limit.resetsAt ?? twin?.resetsAt ?? null,
+        };
+    }
+    return reconciled;
+}
+function scopedLimitFromLegacy(spec, window) {
+    return {
+        dimension: "model",
+        id: null,
+        name: spec.name,
+        usedPct: window.utilization,
+        resetsAt: window.resets_at ?? null,
+    };
+}
+/** The scope of a `limits[]` entry, or null when it names nothing renderable. */
+function scopedLimitFromEntry(limit) {
+    for (const dimension of ["model", "surface"]) {
+        const entry = limit.scope?.[dimension];
+        const id = entry?.id?.trim() || null;
+        const name = entry?.display_name?.trim() || id;
+        if (name) {
+            return {
+                dimension,
+                id,
+                name,
+                usedPct: limit.percent ?? null,
+                resetsAt: limit.resets_at ?? null,
+            };
+        }
+    }
+    return null;
+}
+// The client uses window ids as React keys, so they must be stable across refreshes and
+// unique within a response. An API-supplied id is already an identifier and is used
+// verbatim (ids elsewhere carry punctuation too, e.g. MiniMax's `interval_MiniMax-M2.7`);
+// only a name fallback is normalized. Normalizing an id would collapse `fable-pro` and
+// `fable_pro` into one window.
+function scopedWindowId(limit) {
+    return `weekly_${limit.dimension}_${limit.id ?? normalizeName(limit.name)}`;
+}
+// Backstop for the one residual case identity cannot rule out: an entry whose verbatim id
+// equals another entry's normalized name. Suffix rather than drop, because a missing bar
+// is the bug this change exists to fix.
+function uniqueWindowId(candidate, taken) {
+    if (!taken.has(candidate))
+        return candidate;
+    for (let suffix = 2;; suffix += 1) {
+        const next = `${candidate}_${suffix}`;
+        if (!taken.has(next))
+            return next;
+    }
+}
+function legacyScopedLimits(resp) {
+    const limits = [];
+    for (const spec of LEGACY_SCOPED_WINDOWS) {
+        const window = resp[spec.field];
+        if (window)
+            limits.push(scopedLimitFromLegacy(spec, window));
+    }
+    return limits;
+}
+function unscopedWindows(resp) {
+    const windows = [];
+    for (const spec of UNSCOPED_WINDOWS) {
+        const window = resp[spec.field];
+        if (!window)
+            continue;
+        windows.push(windowFromUsedPct({
+            id: spec.id,
+            label: spec.label,
+            utilizationPct: window.utilization,
+            resetsAt: window.resets_at ?? null,
+            tone: toneFromUsedPct(window.utilization),
+        }));
+    }
+    return windows;
+}
+function scopedWindows(limits) {
+    const taken = new Set();
+    return limits.map((limit) => {
+        const id = uniqueWindowId(scopedWindowId(limit), taken);
+        taken.add(id);
+        // Emitted even at 0% and inactive: a zero bar answers "how much of this model have I
+        // used", and the bar must not come and go between refreshes.
+        return windowFromUsedPct({
+            id,
+            label: `Weekly \u00b7 ${limit.name}`,
+            utilizationPct: limit.usedPct,
+            resetsAt: limit.resetsAt,
+            tone: toneFromUsedPct(limit.usedPct),
+        });
+    });
+}
+// Keep this in sync with Claude Code's Keychain account derivation.
+const CLAUDE_KEYCHAIN_ACCOUNT_PATTERN = /^[a-zA-Z0-9._-]+$/;
+const CLAUDE_KEYCHAIN_FALLBACK_ACCOUNT = "claude-code-user";
+export function claudeKeychainAccount(user = process.env["USER"] || userInfo().username) {
+    return CLAUDE_KEYCHAIN_ACCOUNT_PATTERN.test(user) ? user : CLAUDE_KEYCHAIN_FALLBACK_ACCOUNT;
+}
+async function runSecurityCommand(args) {
+    try {
+        const { stdout } = await execFileAsync("security", args, {
+            timeout: CLAUDE_KEYCHAIN_TIMEOUT_MS,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read Claude Code's account-specific Keychain item, then try the legacy lookup. */
+export async function readClaudeKeychainCredentials(run = runSecurityCommand, account = claudeKeychainAccount()) {
+    const lookups = [
+        ["find-generic-password", "-a", account, "-w", "-s", CLAUDE_KEYCHAIN_SERVICE],
+        ["find-generic-password", "-w", "-s", CLAUDE_KEYCHAIN_SERVICE],
+    ];
+    for (const args of lookups) {
+        const raw = await run(args);
+        if (!raw)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const creds = ClaudeCredentialsSchema.safeParse(parsed);
+        if (creds.success && creds.data.claudeAiOauth?.accessToken)
+            return parsed;
+    }
+    return null;
+}
+export class ClaudeQuotaProvider {
+    constructor(options) {
+        this.providerId = "claude";
+        this.displayName = "Claude";
+        this.logger = options.logger.child({ module: "claude-quota-provider" });
+        this.claudeHome =
+            options.claudeHome ||
+                process.env["CLAUDE_CONFIG_DIR"] ||
+                process.env["CLAUDE_HOME"] ||
+                join(homedir(), ".claude");
+        this.readKeychainCredentials = options.claudeKeychainReader ?? readClaudeKeychainCredentials;
+        this.platform = options.platform ?? process.platform;
+        this.fetchApi = options.fetch ?? fetch;
+    }
+    async fetchUsage() {
+        const credentials = await this.readCredentials();
+        if (!credentials) {
+            return unavailableUsage(this);
+        }
+        const { oauth } = credentials;
+        const plan = buildClaudePlan(oauth.subscriptionType, oauth.rateLimitTier);
+        const resp = await this.callClaudeApi(oauth.accessToken);
+        if (resp === "FORBIDDEN") {
+            return this.forbiddenUsage();
+        }
+        if (resp === "NEEDS_AUTH") {
+            // Read-only on credentials; the Claude CLI owns refresh. See docs/providers.md.
+            // A 403 is handled above and never reaches here, so there is no refreshed-token
+            // retry left to classify.
+            return unavailableUsage(this);
+        }
+        const scoped = reconcileScopedLimits(legacyScopedLimits(resp), this.scopedLimitsFromResponse(resp.limits));
+        const windows = [...unscopedWindows(resp), ...scopedWindows(scoped)];
+        if (windows.length === 0) {
+            // The response parsed but described nothing. That silence is how the previous
+            // shape change went unnoticed, so make it greppable. `warn` and not `debug`
+            // because file logging defaults to `info`.
+            this.logger.warn("Claude usage response parsed but produced no windows");
+        }
+        const details = [];
+        const extraUsageEnabled = resp.extra_usage?.is_enabled;
+        if (extraUsageEnabled !== undefined) {
+            details.push({
+                id: "extra_usage",
+                label: "Extra usage",
+                value: extraUsageEnabled ? "Enabled" : "Disabled",
+            });
+        }
+        return {
+            providerId: this.providerId,
+            displayName: this.displayName,
+            status: "available",
+            planLabel: plan,
+            windows,
+            balances: [],
+            details,
+            error: null,
+        };
+    }
+    /**
+     * Scoped limits carried by `limits[]`.
+     *
+     * Entries are validated one at a time so a single malformed or newly-shaped entry
+     * cannot fail the whole response and take the windows that already parsed with it.
+     */
+    scopedLimitsFromResponse(limits) {
+        if (!limits)
+            return [];
+        const parsed = [];
+        for (const entry of limits) {
+            const result = ClaudeLimitSchema.safeParse(entry);
+            if (!result.success) {
+                this.logger.warn({ err: result.error }, "Skipping unparseable Claude usage limit entry");
+                continue;
+            }
+            if (result.data.kind !== SCOPED_WEEKLY_KIND)
+                continue;
+            const limit = scopedLimitFromEntry(result.data);
+            if (!limit) {
+                this.logger.warn("Skipping scoped Claude usage limit with no resolvable scope name");
+                continue;
+            }
+            parsed.push(limit);
+        }
+        return parsed;
+    }
+    forbiddenUsage() {
+        return unavailableUsage({
+            providerId: this.providerId,
+            displayName: this.displayName,
+            error: CLAUDE_USAGE_FORBIDDEN_MESSAGE,
+        });
+    }
+    async readCredentials() {
+        const credPath = join(this.claudeHome, ".credentials.json");
+        const fileCredentials = await this.readCredentialFile(credPath);
+        return (fileCredentials ?? (this.platform === "darwin" ? await this.readKeychainCredential() : null));
+    }
+    async readCredentialFile(path) {
+        if (!existsSync(path))
+            return null;
+        try {
+            return this.toCredentialRecord(ClaudeCredentialsSchema.parse(JSON.parse(await fs.readFile(path, "utf8"))));
+        }
+        catch {
+            return null;
+        }
+    }
+    async readKeychainCredential() {
+        const parsed = ClaudeCredentialsSchema.safeParse(await this.readKeychainCredentials());
+        return parsed.success ? this.toCredentialRecord(parsed.data) : null;
+    }
+    toCredentialRecord(credentials) {
+        const oauth = credentials.claudeAiOauth;
+        return oauth?.accessToken ? { oauth: { ...oauth, accessToken: oauth.accessToken } } : null;
+    }
+    async callClaudeApi(token) {
+        const res = await fetchProviderApi(this.fetchApi, "https://api.anthropic.com/api/oauth/usage", {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+                "anthropic-beta": CLAUDE_OAUTH_BETA,
+            },
+        });
+        if (res.status === 401)
+            return "NEEDS_AUTH";
+        if (res.status === 403)
+            return "FORBIDDEN";
+        if (!res.ok)
+            throw new Error(`Claude usage API returned ${res.status}`);
+        return ClaudeUsageResponseSchema.parse(await res.json());
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/server/services/quota-fetcher/providers/codex.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from "pino";
+import type { ProviderUsage } from "../../../server/messages.js";
+import type { ProviderApiFetch, ProviderUsageFetcher } from "../provider.js";
+interface CodexQuotaProviderOptions {
+    logger: Logger;
+    codexHome?: string;
+    includeDefaultAuthPaths?: boolean;
+    fetch?: ProviderApiFetch;
+}
+export declare class CodexQuotaProvider implements ProviderUsageFetcher {
+    readonly providerId = "codex";
+    readonly displayName = "Codex";
+    private readonly codexHome;
+    private readonly includeDefaultAuthPaths;
+    private readonly fetchApi;
+    constructor(options: CodexQuotaProviderOptions);
+    fetchUsage(): Promise<ProviderUsage>;
+    private toUsage;
+    private readCodexAuth;
+    private callCodexApi;
+}
+export {};
+//# sourceMappingURL=codex.d.ts.map