pi-openai-usage 0.1.0

package/src/usage-settings.ts

@@ -0,0 +1,331 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  type LoadedUsageConfig,
+  type UsageConfigPatch,
+  loadUsageConfig,
+  patchUsageConfig,
+} from "./config";
+import { resolveCodexOAuthCredentials, type CodexCredentialResolution } from "./auth";
+import { createUsageCommandFacade } from "./usage-command-facade";
+import {
+  createUsageRefreshCoordinator,
+  type UsageRefreshCoordinator,
+} from "./usage-refresh-coordinator";
+import {
+  fetchCodexUsage,
+  type UsageClientPort,
+} from "./usage-client";
+import { type UsageStateStore, createUsageStateStore } from "./usage-state";
+import { formatDiagnosticsReport } from "./diagnostics-reporter";
+import { openInteractiveSettingsMenu } from "./interactive-settings-menu";
+
+type UsageSettingsCommandContext = Pick<
+  ExtensionCommandContext,
+  "ui" | "model" | "modelRegistry" | "signal" | "hasUI"
+>;
+
+type ConfigPatchWriter = (configPath: string, patch: UsageConfigPatch) => void;
+type ConfigChangedCallback = (ctx: UsageSettingsCommandContext) => void | Promise<void>;
+type StatusLineReapplyCallback = (ctx: UsageSettingsCommandContext) => void | Promise<void>;
+
+type UsageSettingsCommandDependencies = {
+  loadConfig?: () => LoadedUsageConfig;
+  resolveCredentials?: (
+    ctx: UsageSettingsCommandContext,
+  ) => Promise<CodexCredentialResolution>;
+  usageClient?: UsageClientPort;
+  usageState?: UsageStateStore;
+  usageRefreshCoordinator?: UsageRefreshCoordinator;
+  patchConfig?: ConfigPatchWriter;
+  onConfigChanged?: ConfigChangedCallback;
+  reapplyStatusLine?: StatusLineReapplyCallback;
+};
+
+const defaultUsageClient: UsageClientPort = {
+  fetchUsage: fetchCodexUsage,
+};
+
+export type { UsageSettingsCommandDependencies };
+
+export function registerOpenAIUsageSettingsCommand(
+  pi: ExtensionAPI,
+  dependencies: UsageSettingsCommandDependencies = {},
+): void {
+  const loadConfig = dependencies.loadConfig ?? loadUsageConfig;
+  const resolveCredentials = dependencies.resolveCredentials ?? defaultResolveCredentials;
+  const usageClient = dependencies.usageClient ?? defaultUsageClient;
+  const usageState = dependencies.usageState ?? createUsageStateStore();
+  const usageRefreshCoordinator =
+    dependencies.usageRefreshCoordinator ??
+    createUsageRefreshCoordinator({ usageClient, usageState });
+  const patchConfig = dependencies.patchConfig ?? patchUsageConfig;
+  const onConfigChanged = dependencies.onConfigChanged ?? noopConfigChanged;
+  const reapplyStatusLine = dependencies.reapplyStatusLine ?? noopStatusLineReapply;
+  const usageCommandFacade = createUsageCommandFacade({
+    loadConfig,
+    resolveCredentials: (ctx) => resolveCredentials(ctx as UsageSettingsCommandContext),
+    usageRefreshCoordinator,
+  });
+
+  pi.registerCommand("openai-usage-settings", {
+    description: "OpenAI usage settings and utility subcommands",
+    getArgumentCompletions(argumentPrefix: string) {
+      return suggestSettingsSubcommands(argumentPrefix);
+    },
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const trimmed = args.trim();
+      const commandContext = asUsageSettingsContext(ctx);
+
+      const lowered = trimmed.toLowerCase();
+      if (trimmed.length === 0) {
+        await handleShowSettings({
+          commandContext,
+          loadConfig,
+          patchConfig,
+          onConfigChanged,
+          reapplyStatusLine,
+        });
+        return;
+      }
+
+      if (isSubcommandInvocation(lowered, "show")) {
+        notify(ctx, removedShowPathText());
+        return;
+      }
+
+      if (isSubcommandInvocation(lowered, "debug")) {
+        notify(ctx, removedDebugPathText());
+        return;
+      }
+
+      if (lowered === "usage") {
+        await usageCommandFacade.showUsage(commandContext);
+        return;
+      }
+
+      if (lowered === "refresh") {
+        await usageCommandFacade.showUsage(commandContext, { forceRefresh: true });
+        return;
+      }
+
+      if (lowered === "help") {
+        notify(ctx, usageSettingsHelpText());
+        return;
+      }
+
+      if (lowered === "diagnostics") {
+        await handleDiagnostics({ commandContext, loadConfig, resolveCredentials, usageState });
+        return;
+      }
+
+      if (isRemovedSetInvocation(lowered)) {
+        notify(ctx, removedSetPathText());
+        return;
+      }
+
+      notify(ctx, "Unknown /openai-usage-settings subcommand. Use /openai-usage-settings help");
+    },
+  });
+}
+
+async function handleShowSettings(options: {
+  commandContext: UsageSettingsCommandContext;
+  loadConfig: () => LoadedUsageConfig;
+  patchConfig: ConfigPatchWriter;
+  onConfigChanged: ConfigChangedCallback;
+  reapplyStatusLine: StatusLineReapplyCallback;
+}): Promise<void> {
+  const { commandContext, loadConfig, patchConfig, onConfigChanged, reapplyStatusLine } = options;
+  if (!commandContext.hasUI || typeof commandContext.ui.custom !== "function") {
+    notify(commandContext, usageSettingsNoUiFallbackText());
+    return;
+  }
+
+  const loaded = loadConfig();
+  await openInteractiveSettingsMenu(commandContext, loaded.effective, {
+    onPatch: (patch) =>
+      handleInteractiveSettingsPatch({
+        commandContext,
+        configPath: loaded.configPath,
+        patch,
+        patchConfig,
+        onConfigChanged,
+        reapplyStatusLine,
+      }),
+  });
+}
+
+function handleInteractiveSettingsPatch(options: {
+  commandContext: UsageSettingsCommandContext;
+  configPath: string;
+  patch: UsageConfigPatch;
+  patchConfig: ConfigPatchWriter;
+  onConfigChanged: ConfigChangedCallback;
+  reapplyStatusLine: StatusLineReapplyCallback;
+}): void {
+  const { commandContext, configPath, patch, patchConfig, onConfigChanged, reapplyStatusLine } =
+    options;
+
+  try {
+    patchConfig(configPath, patch);
+  } catch {
+    return;
+  }
+
+  applySuccessfulMenuWriteSideEffects({
+    commandContext,
+    onConfigChanged,
+    reapplyStatusLine,
+  });
+}
+
+function applySuccessfulMenuWriteSideEffects(options: {
+  commandContext: UsageSettingsCommandContext;
+  onConfigChanged: ConfigChangedCallback;
+  reapplyStatusLine: StatusLineReapplyCallback;
+}): void {
+  const { commandContext, onConfigChanged, reapplyStatusLine } = options;
+
+  try {
+    const configChanged = onConfigChanged(commandContext);
+    if (isPromiseLike(configChanged)) {
+      void Promise.resolve(configChanged)
+        .then(() => reapplyStatusLine(commandContext))
+        .catch(() => undefined);
+      return;
+    }
+
+    const reapplied = reapplyStatusLine(commandContext);
+    if (isPromiseLike(reapplied)) {
+      void Promise.resolve(reapplied).catch(() => undefined);
+    }
+  } catch {
+    return;
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+async function handleDiagnostics(options: {
+  commandContext: UsageSettingsCommandContext;
+  loadConfig: () => LoadedUsageConfig;
+  resolveCredentials: (ctx: UsageSettingsCommandContext) => Promise<CodexCredentialResolution>;
+  usageState: UsageStateStore;
+}): Promise<void> {
+  const { commandContext, loadConfig, resolveCredentials, usageState } = options;
+  const loaded = loadConfig();
+  const credentials = await resolveCredentials(commandContext);
+  notify(
+    commandContext,
+    formatDiagnosticsReport({
+      loaded,
+      credentials,
+      usageState,
+      runtime: commandContext,
+    }),
+  );
+}
+
+function isSubcommandInvocation(loweredArgs: string, subcommand: string): boolean {
+  return loweredArgs === subcommand || loweredArgs.startsWith(`${subcommand} `);
+}
+
+function isRemovedSetInvocation(loweredArgs: string): boolean {
+  return isSubcommandInvocation(loweredArgs, "set");
+}
+
+function removedShowPathText(): string {
+  return [
+    "The /openai-usage-settings show path was removed.",
+    "Common settings are interactive through no-args /openai-usage-settings when UI is available.",
+    "Use /openai-usage-settings help for supported utility subcommands.",
+  ].join("\n");
+}
+
+function removedDebugPathText(): string {
+  return [
+    "The /openai-usage-settings debug path is not a diagnostics alias.",
+    "Use /openai-usage-settings diagnostics for diagnostics.",
+    "Use /openai-usage-settings help for supported utility subcommands.",
+  ].join("\n");
+}
+
+function removedSetPathText(): string {
+  return [
+    "Slash-command setting writes were removed.",
+    "Common settings are interactive now through no-args /openai-usage-settings when UI is available.",
+    "Advanced settings can be edited in the JSON config file.",
+    "Use /openai-usage-settings help for supported utility subcommands.",
+  ].join("\n");
+}
+
+function usageSettingsNoUiFallbackText(): string {
+  return [
+    "Interactive settings require UI.",
+    "This non-UI fallback is read-only and does not change configuration.",
+    "Supported utility subcommands:",
+    "  /openai-usage-settings usage",
+    "  /openai-usage-settings refresh",
+    "  /openai-usage-settings diagnostics",
+    "  /openai-usage-settings help",
+  ].join("\n");
+}
+
+function usageSettingsHelpText(): string {
+  return [
+    "/openai-usage-settings is the only OpenAI usage/settings command.",
+    "Common settings are interactive through no-args /openai-usage-settings when UI is available.",
+    "Advanced settings are JSON-file-only in the usage config file.",
+    "",
+    "Supported utility subcommands:",
+    "  usage        Show cached usage and refresh when stale or missing",
+    "  refresh      Force a usage refresh",
+    "  diagnostics  Show runtime, auth, config, and raw-config diagnostics",
+    "  help         Show this help",
+  ].join("\n");
+}
+
+const SUPPORTED_UTILITY_SUBCOMMANDS = ["usage", "refresh", "diagnostics", "help"] as const;
+
+function suggestSettingsSubcommands(argumentPrefix: string) {
+  const prefix = argumentPrefix.trim().toLowerCase();
+  const matches = SUPPORTED_UTILITY_SUBCOMMANDS
+    .filter((command) => command.startsWith(prefix))
+    .map((command) => ({
+      value: command,
+      label: command,
+    }));
+  return matches.length > 0 ? matches : null;
+}
+
+function asUsageSettingsContext(ctx: ExtensionCommandContext): UsageSettingsCommandContext {
+  return ctx as UsageSettingsCommandContext;
+}
+
+function notify(ctx: UsageSettingsCommandContext, message: string): void {
+  ctx.ui.notify(message, "info");
+}
+
+function noopConfigChanged(_ctx: UsageSettingsCommandContext): void {
+  return undefined;
+}
+
+function noopStatusLineReapply(_ctx: UsageSettingsCommandContext): void {
+  return undefined;
+}
+
+function defaultResolveCredentials(
+  ctx: UsageSettingsCommandContext,
+): Promise<CodexCredentialResolution> {
+  return resolveCodexOAuthCredentials({ modelRegistry: ctx.modelRegistry });
+}

package/src/usage-snapshot.ts

@@ -0,0 +1,136 @@
+export type UsageWindow = {
+  used_percent?: unknown;
+  reset_after_seconds?: unknown;
+  reset_at?: unknown;
+};
+
+export type RateLimitBucket = {
+  allowed?: unknown;
+  limit_reached?: unknown;
+  primary_window?: unknown;
+  secondary_window?: unknown;
+};
+
+export type CodexUsageResponse = {
+  rate_limit?: unknown;
+  additional_rate_limits?: unknown;
+};
+
+export type UsageSnapshot = {
+  fiveHourLeftPercent: number | null;
+  sevenDayLeftPercent: number | null;
+  fiveHourResetInSeconds: number | null;
+  sevenDayResetInSeconds: number | null;
+  isLimited: boolean;
+};
+
+export type ParseUsageSnapshotOptions = {
+  modelId?: string;
+  nowMs?: number;
+};
+
+const SPARK_MODEL_ID = "gpt-5.3-codex-spark";
+const SPARK_LIMIT_NAME = "GPT-5.3-Codex-Spark";
+const MILLISECONDS_EPOCH_THRESHOLD = 100_000_000_000;
+
+export function parseUsageSnapshot(
+  rawResponse: unknown,
+  options: ParseUsageSnapshotOptions = {},
+): UsageSnapshot {
+  const response = asRecord(rawResponse);
+  const rootBucket = normalizeRateLimitBucket(response?.rate_limit);
+  const bucket =
+    options.modelId === SPARK_MODEL_ID
+      ? findSparkRateLimitBucket(response) ?? rootBucket
+      : rootBucket;
+
+  const primaryWindow = asRecord(bucket?.primary_window);
+  const secondaryWindow = asRecord(bucket?.secondary_window);
+
+  return {
+    fiveHourLeftPercent: usedToRemainingPercent(primaryWindow?.used_percent),
+    sevenDayLeftPercent: usedToRemainingPercent(secondaryWindow?.used_percent),
+    fiveHourResetInSeconds: resetInSeconds(primaryWindow, options.nowMs),
+    sevenDayResetInSeconds: resetInSeconds(secondaryWindow, options.nowMs),
+    isLimited: bucket?.allowed === false || bucket?.limit_reached === true,
+  };
+}
+
+function normalizeRateLimitBucket(value: unknown): RateLimitBucket | undefined {
+  const record = asRecord(value);
+  if (record === undefined) return undefined;
+
+  if (
+    !("primary_window" in record) &&
+    !("secondary_window" in record) &&
+    !("allowed" in record) &&
+    !("limit_reached" in record)
+  ) {
+    return undefined;
+  }
+
+  return record;
+}
+
+function findSparkRateLimitBucket(
+  response: Record<string, unknown> | undefined,
+): RateLimitBucket | undefined {
+  if (response === undefined) return undefined;
+
+  const additionalRateLimits = response.additional_rate_limits;
+  if (Array.isArray(additionalRateLimits)) {
+    for (const entry of additionalRateLimits) {
+      const bucket = extractSparkBucketFromEntry(entry);
+      if (bucket !== undefined) return bucket;
+    }
+    return undefined;
+  }
+
+  const additionalRateLimitMap = asRecord(additionalRateLimits);
+  if (additionalRateLimitMap === undefined) return undefined;
+
+  for (const entry of Object.values(additionalRateLimitMap)) {
+    const bucket = extractSparkBucketFromEntry(entry);
+    if (bucket !== undefined) return bucket;
+  }
+  return undefined;
+}
+
+function extractSparkBucketFromEntry(entry: unknown): RateLimitBucket | undefined {
+  const record = asRecord(entry);
+  if (record?.limit_name !== SPARK_LIMIT_NAME) return undefined;
+  return normalizeRateLimitBucket(record.rate_limit);
+}
+
+function usedToRemainingPercent(value: unknown): number | null {
+  if (!isFiniteNumber(value)) return null;
+  return clampPercent(100 - value);
+}
+
+function clampPercent(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}
+
+function resetInSeconds(
+  window: Record<string, unknown> | undefined,
+  nowMs = Date.now(),
+): number | null {
+  const resetAfterSeconds = window?.reset_after_seconds;
+  if (isFiniteNumber(resetAfterSeconds)) return Math.max(0, resetAfterSeconds);
+
+  const resetAt = window?.reset_at;
+  if (!isFiniteNumber(resetAt)) return null;
+
+  const resetAtSeconds =
+    resetAt > MILLISECONDS_EPOCH_THRESHOLD ? resetAt / 1000 : resetAt;
+  return Math.max(0, resetAtSeconds - nowMs / 1000);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}

package/src/usage-state.ts

@@ -0,0 +1,66 @@
+import type { UsageFetchError } from "./usage-client";
+import { parseUsageSnapshot, type UsageSnapshot } from "./usage-snapshot";
+
+export type UsageStateStore = {
+  getSnapshot(modelId?: string): UsageSnapshot | undefined;
+  storeSnapshot(snapshot: UsageSnapshot, fetchedAt?: Date): void;
+  storeRawUsageResponse(rawResponse: unknown, fetchedAt?: Date): void;
+  getLastAttemptAt(): Date | undefined;
+  getLastSuccessAt(): Date | undefined;
+  getLastError(): UsageFetchError | undefined;
+  getCurrentError(): UsageFetchError | undefined;
+  recordFetchAttempt(at?: Date): void;
+  recordFetchError(error: UsageFetchError, attemptedAt?: Date): void;
+};
+
+export function createUsageStateStore(): UsageStateStore {
+  let snapshot: UsageSnapshot | undefined;
+  let rawUsageResponse: unknown | undefined;
+  let lastAttemptAt: Date | undefined;
+  let lastSuccessAt: Date | undefined;
+  let lastError: UsageFetchError | undefined;
+  let currentError: UsageFetchError | undefined;
+
+  return {
+    getSnapshot(modelId) {
+      if (rawUsageResponse !== undefined) {
+        return parseUsageSnapshot(rawUsageResponse, { modelId });
+      }
+      return snapshot;
+    },
+    storeSnapshot(nextSnapshot, fetchedAt = new Date()) {
+      snapshot = nextSnapshot;
+      rawUsageResponse = undefined;
+      lastAttemptAt = fetchedAt;
+      lastSuccessAt = fetchedAt;
+      currentError = undefined;
+    },
+    storeRawUsageResponse(nextRawUsageResponse, fetchedAt = new Date()) {
+      rawUsageResponse = nextRawUsageResponse;
+      snapshot = parseUsageSnapshot(nextRawUsageResponse);
+      lastAttemptAt = fetchedAt;
+      lastSuccessAt = fetchedAt;
+      currentError = undefined;
+    },
+    getLastAttemptAt() {
+      return lastAttemptAt;
+    },
+    getLastSuccessAt() {
+      return lastSuccessAt;
+    },
+    getLastError() {
+      return lastError;
+    },
+    getCurrentError() {
+      return currentError;
+    },
+    recordFetchAttempt(at = new Date()) {
+      lastAttemptAt = at;
+    },
+    recordFetchError(error, attemptedAt = new Date()) {
+      lastAttemptAt = attemptedAt;
+      currentError = error;
+      lastError = error;
+    },
+  };
+}

package/src/visibility.ts

@@ -0,0 +1,39 @@
+export type UsageModel = {
+  provider: string;
+  id?: string;
+};
+
+export type UsageModelRegistry = {
+  isUsingOAuth(model: UsageModel): boolean;
+};
+
+export type UsageVisibilityInput = {
+  showAlways: boolean;
+  model: UsageModel | undefined;
+  modelRegistry: UsageModelRegistry | undefined;
+};
+
+export type UsageVisibilityDecision =
+  | { visible: true; reason: "show_always" | "eligible_model" }
+  | { visible: false; reason: "ineligible_model" };
+
+const ELIGIBLE_USAGE_PROVIDERS = new Set(["openai", "openai-codex"]);
+
+export function decideUsageVisibility(input: UsageVisibilityInput): UsageVisibilityDecision {
+  if (input.showAlways) return { visible: true, reason: "show_always" };
+
+  if (isUsageEligibleModel(input.model, input.modelRegistry)) {
+    return { visible: true, reason: "eligible_model" };
+  }
+
+  return { visible: false, reason: "ineligible_model" };
+}
+
+export function isUsageEligibleModel(
+  model: UsageModel | undefined,
+  modelRegistry: UsageModelRegistry | undefined,
+): boolean {
+  if (model === undefined) return false;
+  if (!ELIGIBLE_USAGE_PROVIDERS.has(model.provider)) return false;
+  return modelRegistry?.isUsingOAuth(model) === true;
+}