axusage 3.5.0 → 3.7.0

package/dist/commands/usage-command.d.ts

@@ -2,6 +2,7 @@ import type { ServiceResult } from "../types/domain.js";
 import type { UsageCommandOptions } from "./fetch-service-usage.js";
 /**
  * Fetches usage for all requested services in parallel.
+ * Each service type may produce multiple results (multi-instance support).
  */
 export declare function fetchServicesInParallel(servicesToQuery: string[]): Promise<ServiceResult[]>;
 /**

package/dist/commands/usage-command.js

@@ -1,16 +1,15 @@
 import { formatServiceUsageData, formatServiceUsageDataAsJson, formatServiceUsageAsTsv, toJsonObject, } from "../utils/format-service-usage.js";
 import { formatPrometheusMetrics } from "../utils/format-prometheus-metrics.js";
-import { fetchServiceUsage, selectServicesToQuery, } from "./fetch-service-usage.js";
+import { fetchServiceInstanceUsage, selectServicesToQuery, } from "./fetch-service-usage.js";
 import { isAuthFailure } from "./run-auth-setup.js";
 import { chalk } from "../utils/color.js";
 /**
  * Fetches usage for all requested services in parallel.
+ * Each service type may produce multiple results (multi-instance support).
  */
 export async function fetchServicesInParallel(servicesToQuery) {
-    return await Promise.all(servicesToQuery.map(async (serviceName) => {
-        const result = await fetchServiceUsage(serviceName);
-        return { service: serviceName, result };
-    }));
+    const nestedResults = await Promise.all(servicesToQuery.map((serviceName) => fetchServiceInstanceUsage(serviceName)));
+    return nestedResults.flat();
 }
 /**
  * Executes the usage command
@@ -74,9 +73,10 @@ export async function usageCommand(options) {
                 console.log(formatServiceUsageDataAsJson(singleSuccess));
             }
             else {
+                const now = Date.now();
                 const payload = successes.length === 1 && singleSuccess
-                    ? toJsonObject(singleSuccess)
-                    : successes.map((data) => toJsonObject(data));
+                    ? toJsonObject(singleSuccess, now)
+                    : successes.map((data) => toJsonObject(data, now));
                 const output = hasPartialFailures
                     ? {
                         results: payload,
@@ -94,7 +94,7 @@ export async function usageCommand(options) {
         }
         case "prometheus": {
             // Emit Prometheus text metrics using prom-client
-            const output = await formatPrometheusMetrics(successes);
+            const output = await formatPrometheusMetrics(successes, Date.now());
             process.stdout.write(output);
             break;
         }

package/dist/config/credential-sources.d.ts

@@ -4,7 +4,9 @@
  * Supports three modes:
  * - "local": Use local credentials from axauth (default behavior)
  * - "vault": Fetch credentials from axvault server
- * - "auto": Try vault first if configured and credential name provided, fallback to local
+ * - "auto": Without a credential name, uses local credentials. With a named
+ *   credential, requires vault (no local fallback) to prevent returning the same
+ *   local token for multiple instances. Vault must be configured for named credentials.
  */
 import { z } from "zod";
 import type { SupportedService } from "../services/supported-service.js";
@@ -15,18 +17,12 @@ declare const CredentialSourceType: z.ZodEnum<{
     vault: "vault";
 }>;
 type CredentialSourceType = z.infer<typeof CredentialSourceType>;
-/** Resolved source config with normalized fields */
-interface ResolvedSourceConfig {
+/** Resolved instance config with display name */
+interface ResolvedInstanceConfig {
     source: CredentialSourceType;
     name: string | undefined;
+    displayName: string | undefined;
 }
-/**
- * Get the resolved source config for a specific service.
- *
- * @param service - Service ID (e.g., "claude", "codex", "gemini")
- * @returns Resolved config with source type and optional credential name
- */
-declare function getServiceSourceConfig(service: SupportedService): ResolvedSourceConfig;
 /**
  * Get the credential sources config file path.
  *
@@ -35,4 +31,13 @@ declare function getServiceSourceConfig(service: SupportedService): ResolvedSour
  * directory during construction).
  */
 declare function getCredentialSourcesPath(): string;
-export { getServiceSourceConfig, getCredentialSourcesPath };
+/**
+ * Get all instance configs for a service, normalizing all config forms to an array.
+ *
+ * - String shorthand → single instance with that source
+ * - Object → single instance
+ * - Array → multiple instances
+ */
+declare function getServiceInstanceConfigs(service: SupportedService): ResolvedInstanceConfig[];
+export { getServiceInstanceConfigs, getCredentialSourcesPath };
+export type { ResolvedInstanceConfig };

package/dist/config/credential-sources.js

@@ -4,7 +4,9 @@
  * Supports three modes:
  * - "local": Use local credentials from axauth (default behavior)
  * - "vault": Fetch credentials from axvault server
- * - "auto": Try vault first if configured and credential name provided, fallback to local
+ * - "auto": Without a credential name, uses local credentials. With a named
+ *   credential, requires vault (no local fallback) to prevent returning the same
+ *   local token for multiple instances. Vault must be configured for named credentials.
  */
 import Conf from "conf";
 import envPaths from "env-paths";
@@ -12,13 +14,17 @@ import path from "node:path";
 import { z } from "zod";
 /** Credential source type */
 const CredentialSourceType = z.enum(["auto", "local", "vault"]);
-/** Service source config - either a string shorthand or object with name */
+/** Instance source config - object form with optional name and displayName */
+const InstanceSourceConfig = z.object({
+    source: CredentialSourceType,
+    name: z.string().min(1).optional(),
+    displayName: z.string().min(1).optional(),
+});
+/** Service source config - string shorthand, object, or array of objects */
 const ServiceSourceConfig = z.union([
     CredentialSourceType,
-    z.object({
-        source: CredentialSourceType,
-        name: z.string().optional(),
-    }),
+    InstanceSourceConfig,
+    z.array(InstanceSourceConfig).min(1),
 ]);
 /** Full sources config - map of service ID to source config */
 const SourcesConfig = z.record(z.string(), ServiceSourceConfig);
@@ -96,26 +102,6 @@ function getCredentialSourceConfig() {
     // Priority 3: Empty (defaults apply)
     return {};
 }
-/**
- * Get the resolved source config for a specific service.
- *
- * @param service - Service ID (e.g., "claude", "codex", "gemini")
- * @returns Resolved config with source type and optional credential name
- */
-function getServiceSourceConfig(service) {
-    const config = getCredentialSourceConfig();
-    const serviceConfig = config[service];
-    // Default: auto mode with no credential name
-    if (serviceConfig === undefined) {
-        return { source: "auto", name: undefined };
-    }
-    // String shorthand: just the source type
-    if (typeof serviceConfig === "string") {
-        return { source: serviceConfig, name: undefined };
-    }
-    // Object: source and name
-    return { source: serviceConfig.source, name: serviceConfig.name };
-}
 /**
  * Get the credential sources config file path.
  *
@@ -127,4 +113,39 @@ function getCredentialSourcesPath() {
     const configDirectory = envPaths("axusage", { suffix: "" }).config;
     return path.resolve(configDirectory, "config.json");
 }
-export { getServiceSourceConfig, getCredentialSourcesPath };
+/**
+ * Get all instance configs for a service, normalizing all config forms to an array.
+ *
+ * - String shorthand → single instance with that source
+ * - Object → single instance
+ * - Array → multiple instances
+ */
+function getServiceInstanceConfigs(service) {
+    const config = getCredentialSourceConfig();
+    const serviceConfig = config[service];
+    // Default: single auto instance
+    if (serviceConfig === undefined) {
+        return [{ source: "auto", name: undefined, displayName: undefined }];
+    }
+    // String shorthand: single instance with that source
+    if (typeof serviceConfig === "string") {
+        return [{ source: serviceConfig, name: undefined, displayName: undefined }];
+    }
+    // Array: multiple instances
+    if (Array.isArray(serviceConfig)) {
+        return serviceConfig.map((instance) => ({
+            source: instance.source,
+            name: instance.name,
+            displayName: instance.displayName,
+        }));
+    }
+    // Object: single instance
+    return [
+        {
+            source: serviceConfig.source,
+            name: serviceConfig.name,
+            displayName: serviceConfig.displayName,
+        },
+    ];
+}
+export { getServiceInstanceConfigs, getCredentialSourcesPath };

package/dist/server/routes.js

@@ -27,6 +27,8 @@ export function createMetricsRouter(getState) {
     // Memoize the rendered Prometheus text by the state snapshot's refreshedAt
     // timestamp. Scrapes within the same cache window reuse the same Promise,
     // avoiding recreating prom-client Registry/Gauge objects on each request.
+    // Rate is computed at refreshedAt so output is deterministic per snapshot,
+    // keeping the gauge coherent with the usage data it describes.
     // Assignments happen synchronously (before any await) so require-atomic-updates
     // is satisfied and concurrent scrapes naturally coalesce onto one render.
     let memoFor;
@@ -40,7 +42,7 @@ export function createMetricsRouter(getState) {
         }
         if (memoFor !== state.refreshedAt) {
             memoFor = state.refreshedAt;
-            memoPromise = formatPrometheusMetrics(usage);
+            memoPromise = formatPrometheusMetrics(usage, state.refreshedAt.getTime());
         }
         const text = await memoPromise;
         response
@@ -60,7 +62,9 @@ export function createUsageRouter(getFreshState) {
             response.status(503).json({ error: "No data yet" });
             return;
         }
-        response.status(200).json(usage.map((entry) => toJsonObject(entry)));
+        response
+            .status(200)
+            .json(usage.map((entry) => toJsonObject(entry, state.refreshedAt.getTime())));
     });
     return router;
 }

package/dist/services/get-instance-access-token.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Instance-aware credential fetcher.
+ *
+ * Resolves an access token for a specific service instance config,
+ * returning vault metadata (displayName) alongside the token.
+ */
+import type { ResolvedInstanceConfig } from "../config/credential-sources.js";
+/** Result of resolving an instance token */
+interface InstanceTokenResult {
+    token: string | undefined;
+    vaultDisplayName: string | undefined;
+}
+/**
+ * Get access token for a specific service instance.
+ *
+ * Returns vault metadata (displayName) alongside the token
+ * for multi-instance identification.
+ */
+declare function getInstanceAccessToken(service: string, config: ResolvedInstanceConfig): Promise<InstanceTokenResult>;
+export { getInstanceAccessToken };

package/dist/services/{get-service-access-token.js → get-instance-access-token.js}

@@ -1,13 +1,10 @@
 /**
- * Unified credential fetcher for services.
+ * Instance-aware credential fetcher.
  *
- * Fetches access tokens based on per-service configuration:
- * - "local": From local axauth credential store
- * - "vault": From axvault server
- * - "auto": Try vault first if configured, fallback to local
+ * Resolves an access token for a specific service instance config,
+ * returning vault metadata (displayName) alongside the token.
  */
 import { fetchVaultCredentials, getAgentAccessToken, isVaultConfigured, } from "axauth";
-import { getServiceSourceConfig } from "../config/credential-sources.js";
 import { getCopilotTokenFromCustomGhPath } from "../utils/copilot-gh-token.js";
 /**
  * Extract access token from vault credentials.
@@ -42,41 +39,32 @@ function extractAccessToken(credentials) {
     }
     return undefined;
 }
-/**
- * Fetch access token from vault.
- *
- * @returns Access token string or undefined if not available
- */
-async function fetchFromVault(agentId, credentialName) {
+/** Fetch access token from vault, returning metadata alongside the token */
+async function fetchFromVaultWithMetadata(agentId, credentialName) {
     try {
         const result = await fetchVaultCredentials({
             agentId,
             name: credentialName,
         });
         if (!result.ok) {
-            // Log warning for debugging, but don't fail hard
             if (result.reason !== "not-configured" && result.reason !== "not-found") {
                 console.error(`[axusage] Vault fetch failed for ${agentId}/${credentialName}: ${result.reason}`);
             }
-            return undefined;
+            return { token: undefined, vaultDisplayName: undefined };
         }
         const token = extractAccessToken(result.credentials);
         if (!token) {
             console.error(`[axusage] Vault credentials for ${agentId}/${credentialName} missing access token. ` +
                 `Credential type: ${result.credentials.type}`);
         }
-        return token;
+        return { token, vaultDisplayName: result.displayName };
     }
     catch (error) {
         console.error(`[axusage] Vault fetch error for ${agentId}/${credentialName}: ${error instanceof Error ? error.message : String(error)}`);
-        return undefined;
+        return { token: undefined, vaultDisplayName: undefined };
     }
 }
-/**
- * Fetch access token from local credential store.
- *
- * @returns Access token string or undefined if not available
- */
+/** Fetch access token from local credential store */
 async function fetchFromLocal(agentId) {
     try {
         const token = await getAgentAccessToken(agentId);
@@ -92,55 +80,46 @@ async function fetchFromLocal(agentId) {
     return undefined;
 }
 /**
- * Get access token for a service.
- *
- * Uses the configured credential source for the service:
- * - "local": Fetch from local axauth credential store
- * - "vault": Fetch from axvault server (requires credential name)
- * - "auto": Try vault if configured and name provided, fallback to local
+ * Get access token for a specific service instance.
  *
- * @param service - Service ID (e.g., "claude", "codex", "gemini")
- * @returns Access token string or undefined if not available
- *
- * @example
- * const token = await getServiceAccessToken("claude");
- * if (!token) {
- *   console.error("No credentials found for Claude");
- * }
+ * Returns vault metadata (displayName) alongside the token
+ * for multi-instance identification.
  */
-async function getServiceAccessToken(service) {
-    const config = getServiceSourceConfig(service);
+async function getInstanceAccessToken(service, config) {
     const agentId = service;
     switch (config.source) {
         case "local": {
-            return fetchFromLocal(agentId);
+            const token = await fetchFromLocal(agentId);
+            return { token, vaultDisplayName: undefined };
         }
         case "vault": {
             if (!config.name) {
                 console.error(`[axusage] Vault source requires credential name for ${service}. ` +
                     `Set {"${service}": {"source": "vault", "name": "your-name"}} in config.`);
-                return undefined;
+                return { token: undefined, vaultDisplayName: undefined };
             }
-            const token = await fetchFromVault(agentId, config.name);
-            if (!token) {
-                // User explicitly selected vault but it failed - provide clear feedback
+            const result = await fetchFromVaultWithMetadata(agentId, config.name);
+            if (!result.token) {
                 console.error(`[axusage] Vault credential fetch failed for ${service}. ` +
                     `Check that vault is configured (AXVAULT env) and credential "${config.name}" exists.`);
             }
-            return token;
+            return result;
         }
         case "auto": {
-            // Auto mode: try vault first if configured and name provided
-            if (config.name && isVaultConfigured()) {
-                const vaultToken = await fetchFromVault(agentId, config.name);
-                if (vaultToken) {
-                    return vaultToken;
+            if (config.name) {
+                // Named credential: vault-only to avoid silently returning
+                // the same local token for multiple instances
+                if (!isVaultConfigured()) {
+                    console.error(`[axusage] Named credential "${config.name}" for ${service} requires vault, ` +
+                        `but vault is not configured. Set AXVAULT env or use source "local" instead.`);
+                    return { token: undefined, vaultDisplayName: undefined };
                 }
-                // Fallback to local if vault failed
+                return fetchFromVaultWithMetadata(agentId, config.name);
             }
-            // No credential name or vault not configured: use local only
-            return fetchFromLocal(agentId);
+            // No credential name: use local
+            const token = await fetchFromLocal(agentId);
+            return { token, vaultDisplayName: undefined };
         }
     }
 }
-export { getServiceAccessToken };
+export { getInstanceAccessToken };

package/dist/services/resolve-service-instances.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure functions for resolving display names for service instances.
+ *
+ * Priority: config displayName > vault displayName > auto-number (multi) / adapter default (single)
+ */
+/**
+ * Resolve the display name for a service instance.
+ *
+ * For single-instance configs: config displayName > vault displayName > adapter default name
+ * For multi-instance without displayName: "Claude #1", "Claude #2"
+ */
+declare function resolveInstanceDisplayName(configDisplayName: string | undefined, vaultDisplayName: string | undefined, defaultName: string, index: number, total: number): string;
+export { resolveInstanceDisplayName };

package/dist/services/resolve-service-instances.js

@@ -0,0 +1,24 @@
+/**
+ * Pure functions for resolving display names for service instances.
+ *
+ * Priority: config displayName > vault displayName > auto-number (multi) / adapter default (single)
+ */
+/**
+ * Resolve the display name for a service instance.
+ *
+ * For single-instance configs: config displayName > vault displayName > adapter default name
+ * For multi-instance without displayName: "Claude #1", "Claude #2"
+ */
+function resolveInstanceDisplayName(configDisplayName, vaultDisplayName, defaultName, index, total) {
+    // Explicit displayName always wins
+    if (configDisplayName)
+        return configDisplayName;
+    if (vaultDisplayName)
+        return vaultDisplayName;
+    // Single instance: use adapter default
+    if (total === 1)
+        return defaultName;
+    // Multi-instance without displayName: auto-number
+    return `${defaultName} #${String(index + 1)}`;
+}
+export { resolveInstanceDisplayName };

package/dist/services/service-adapter-registry.d.ts

@@ -1,17 +1,8 @@
-import type { ServiceAdapter } from "../types/domain.js";
+import type { ServiceUsageFetcher } from "../types/domain.js";
 /**
- * Registry of available service adapters
+ * Get a token-based usage fetcher by service type
  */
-export declare const SERVICE_ADAPTERS: {
-    readonly claude: ServiceAdapter;
-    readonly codex: ServiceAdapter;
-    readonly copilot: ServiceAdapter;
-    readonly gemini: ServiceAdapter;
-};
-/**
- * Get a service adapter by name
- */
-export declare function getServiceAdapter(name: string): ServiceAdapter | undefined;
+export declare function getServiceUsageFetcher(name: string): ServiceUsageFetcher | undefined;
 /**
  * Get all available service names
  */

package/dist/services/service-adapter-registry.js

@@ -1,26 +1,26 @@
-import { codexAdapter } from "../adapters/codex.js";
-import { claudeAdapter } from "../adapters/claude.js";
-import { geminiAdapter } from "../adapters/gemini.js";
-import { copilotAdapter } from "../adapters/copilot.js";
+import { codexUsageFetcher } from "../adapters/codex.js";
+import { claudeUsageFetcher } from "../adapters/claude.js";
+import { geminiUsageFetcher } from "../adapters/gemini.js";
+import { copilotUsageFetcher } from "../adapters/copilot.js";
 /**
- * Registry of available service adapters
+ * Registry of token-based usage fetchers
  */
-export const SERVICE_ADAPTERS = {
-    claude: claudeAdapter,
-    codex: codexAdapter,
-    copilot: copilotAdapter,
-    gemini: geminiAdapter,
+const SERVICE_USAGE_FETCHERS = {
+    claude: claudeUsageFetcher,
+    codex: codexUsageFetcher,
+    copilot: copilotUsageFetcher,
+    gemini: geminiUsageFetcher,
 };
 /**
- * Get a service adapter by name
+ * Get a token-based usage fetcher by service type
  */
-export function getServiceAdapter(name) {
+export function getServiceUsageFetcher(name) {
     const key = name.toLowerCase();
-    return SERVICE_ADAPTERS[key];
+    return SERVICE_USAGE_FETCHERS[key];
 }
 /**
  * Get all available service names
  */
 export function getAvailableServices() {
-    return Object.keys(SERVICE_ADAPTERS);
+    return Object.keys(SERVICE_USAGE_FETCHERS);
 }

package/dist/types/domain.d.ts

@@ -14,7 +14,12 @@ export type UsageWindow = {
  * Complete usage data for a service
  */
 export type ServiceUsageData = {
+    /** Display name (may be overridden by instance displayName) */
     readonly service: string;
+    /** Stable machine key (e.g., "claude", "codex") for filtering and labeling */
+    readonly serviceType: string;
+    /** Stable per-instance identifier for metrics (derived from credential name or config key) */
+    readonly instanceId?: string;
     readonly planType?: string;
     readonly windows: readonly UsageWindow[];
     readonly metadata?: {
@@ -41,11 +46,12 @@ export declare class ApiError extends Error {
     constructor(message: string, status?: number, body?: unknown);
 }
 /**
- * Service adapter interface
+ * Token-based usage fetcher for a service.
+ * Tokens are resolved externally via credential sources.
  */
-export interface ServiceAdapter {
+export interface ServiceUsageFetcher {
     readonly name: string;
-    fetchUsage(): Promise<Result<ServiceUsageData, ApiError>>;
+    fetchUsageWithToken(accessToken: string): Promise<Result<ServiceUsageData, ApiError>>;
 }
 /**
  * Result of fetching usage for a single service.

package/dist/utils/calculate-usage-rate.d.ts

@@ -6,4 +6,4 @@
  * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
  * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
  */
-export declare function calculateUsageRate(utilization: number, resetsAt: Date | undefined, periodDurationMs: number): number | undefined;
+export declare function calculateUsageRate(utilization: number, resetsAt: Date | undefined, periodDurationMs: number, now: number): number | undefined;

package/dist/utils/calculate-usage-rate.js

@@ -10,12 +10,11 @@ const MIN_ELAPSED_TIME_MS = 2 * 60 * 60 * 1000;
  * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
  * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
  */
-export function calculateUsageRate(utilization, resetsAt, periodDurationMs) {
+export function calculateUsageRate(utilization, resetsAt, periodDurationMs, now) {
     if (!resetsAt)
         return undefined;
     if (periodDurationMs <= 0)
         return 0;
-    const now = Date.now();
     const resetTime = resetsAt.getTime();
     const periodStart = resetTime - periodDurationMs;
     const elapsedTime = now - periodStart;

package/dist/utils/format-prometheus-metrics.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceUsageData } from "../types/domain.js";
 /**
  * Formats service usage data as Prometheus text exposition using prom-client.
- * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ * Emits gauges `axusage_utilization_percent` and `axusage_usage_rate` per window.
  */
-export declare function formatPrometheusMetrics(data: readonly ServiceUsageData[]): Promise<string>;
+export declare function formatPrometheusMetrics(data: readonly ServiceUsageData[], now: number): Promise<string>;

package/dist/utils/format-prometheus-metrics.js

@@ -1,19 +1,36 @@
 import { Gauge, Registry } from "prom-client";
+import { calculateUsageRate } from "./calculate-usage-rate.js";
 /**
  * Formats service usage data as Prometheus text exposition using prom-client.
- * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ * Emits gauges `axusage_utilization_percent` and `axusage_usage_rate` per window.
  */
-export async function formatPrometheusMetrics(data) {
+export async function formatPrometheusMetrics(data, now) {
     const registry = new Registry();
-    const gauge = new Gauge({
+    const utilizationGauge = new Gauge({
         name: "axusage_utilization_percent",
         help: "Current utilization percentage by service/window",
-        labelNames: ["service", "window"],
+        labelNames: ["service", "service_type", "instance_id", "window"],
+        registers: [registry],
+    });
+    const rateGauge = new Gauge({
+        name: "axusage_usage_rate",
+        help: "Usage rate (utilization / elapsed fraction of period); >1 means over budget",
+        labelNames: ["service", "service_type", "instance_id", "window"],
         registers: [registry],
     });
     for (const entry of data) {
         for (const w of entry.windows) {
-            gauge.set({ service: entry.service, window: w.name }, w.utilization);
+            const labels = {
+                service: entry.service,
+                service_type: entry.serviceType,
+                instance_id: entry.instanceId ?? entry.serviceType,
+                window: w.name,
+            };
+            utilizationGauge.set(labels, w.utilization);
+            const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs, now);
+            if (rate !== undefined) {
+                rateGauge.set(labels, rate);
+            }
         }
     }
     return registry.metrics();

package/dist/utils/format-service-usage.d.ts

@@ -6,7 +6,7 @@ export declare function formatServiceUsageData(data: ServiceUsageData): string;
 /**
  * Converts service usage data to a plain JSON-serializable object
  */
-export declare function toJsonObject(data: ServiceUsageData): unknown;
+export declare function toJsonObject(data: ServiceUsageData, now: number): unknown;
 /**
  * Formats service usage data as JSON string
  */