pi-harness-runtime 0.9.2 → 0.9.5

package/packages/quota-manager/src/quota-manager.ts

@@ -0,0 +1,339 @@
+/**
+ * Quota Manager — RFC-0003
+ *
+ * Collects quota signals from API responses, provider status,
+ * Playwright, and local estimates. Produces provider availability state.
+ */
+
+import type {
+	QuotaSignal,
+	QuotaState,
+} from "../../packages/types/src/runtime-types.js";
+
+export interface QuotaSignalInput {
+	provider: string;
+	source:
+		| "api_response"
+		| "provider_status"
+		| "playwright"
+		| "local_estimate"
+		| "tui_message";
+	windowType: "5h" | "daily" | "weekly" | "monthly";
+	usedPct?: number;
+	exhausted?: boolean;
+	resetsAt?: string;
+	retryAfterMs?: number;
+}
+
+export class QuotaManager {
+	private signals: Map<string, QuotaSignal[]> = new Map();
+	private readonly staleThresholdMs: number;
+
+	constructor(staleThresholdMs: number = 30 * 60 * 1000) {
+		this.staleThresholdMs = staleThresholdMs;
+	}
+
+	/**
+	 * Record a quota signal
+	 */
+	recordSignal(input: QuotaSignalInput): void {
+		const signal: QuotaSignal = {
+			provider: input.provider,
+			windowType: input.windowType,
+			usedPct: input.usedPct ?? 0,
+			remainingPct: 100 - (input.usedPct ?? 0),
+			exhausted: input.exhausted ?? false,
+			source: input.source,
+			capturedAt: new Date().toISOString(),
+			resetsAt: input.resetsAt,
+		};
+
+		const key = `${input.provider}:${input.windowType}`;
+		const existing = this.signals.get(key) ?? [];
+		this.signals.set(key, [...existing, signal]);
+	}
+
+	/**
+	 * Get the latest signal for a provider
+	 */
+	getLatestSignal(
+		provider: string,
+		windowType?: "5h" | "daily" | "weekly" | "monthly",
+	): QuotaSignal | null {
+		const key = windowType ? `${provider}:${windowType}` : provider;
+
+		if (windowType) {
+			const signals = this.signals.get(key) ?? [];
+			return (
+				signals.sort(
+					(a, b) => Date.parse(b.capturedAt) - Date.parse(a.capturedAt),
+				)[0] ?? null
+			);
+		}
+
+		// Return most recent across all window types
+		let latest: QuotaSignal | null = null;
+		let latestTs = 0;
+
+		for (const entry of Array.from(this.signals.entries())) {
+			const [k, sigs] = entry;
+			if (k.startsWith(`${provider}:`)) {
+				const mostRecent = sigs.sort(
+					(a: QuotaSignal, b: QuotaSignal) =>
+						Date.parse(b.capturedAt) - Date.parse(a.capturedAt),
+				)[0];
+				if (mostRecent) {
+					const ts = Date.parse(mostRecent.capturedAt);
+					if (ts > latestTs) {
+						latestTs = ts;
+						latest = mostRecent;
+					}
+				}
+			}
+		}
+
+		return latest;
+	}
+
+	/**
+	 * Get quota state for a provider
+	 */
+	getProviderState(provider: string): QuotaState {
+		const signals = this.getSignals(provider);
+		const exhausted = signals.some(
+			(s) => s.exhausted || (s.usedPct !== undefined && s.usedPct >= 100),
+		);
+		const limited = signals.some(
+			(s) => s.usedPct !== undefined && s.usedPct >= 90,
+		);
+
+		// Find next reset time
+		let nextAvailableAt: string | undefined;
+		for (const signal of signals) {
+			if (signal.resetsAt) {
+				if (
+					!nextAvailableAt ||
+					Date.parse(signal.resetsAt) < Date.parse(nextAvailableAt)
+				) {
+					nextAvailableAt = signal.resetsAt;
+				}
+			}
+		}
+
+		return {
+			provider,
+			available: !exhausted && !limited,
+			limited,
+			exhausted,
+			signals,
+			nextAvailableAt,
+		};
+	}
+
+	/**
+	 * Get signals for a provider
+	 */
+	getSignals(provider: string): QuotaSignal[] {
+		const result: QuotaSignal[] = [];
+		const cutoff = Date.now() - this.staleThresholdMs;
+
+		for (const entry of Array.from(this.signals.entries())) {
+			const [key, sigs] = entry;
+			if (key.startsWith(`${provider}:`)) {
+				for (const signal of sigs) {
+					if (Date.parse(signal.capturedAt) >= cutoff) {
+						result.push(signal);
+					}
+				}
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Check if provider is available
+	 */
+	isAvailable(provider: string): boolean {
+		return this.getProviderState(provider).available;
+	}
+
+	/**
+	 * Check if provider is exhausted
+	 */
+	isExhausted(provider: string): boolean {
+		return this.getProviderState(provider).exhausted;
+	}
+
+	/**
+	 * Get time until provider is available again
+	 */
+	getWaitTime(provider: string): number | null {
+		const state = this.getProviderState(provider);
+		if (!state.nextAvailableAt) return null;
+
+		const waitMs = Date.parse(state.nextAvailableAt) - Date.now();
+		return waitMs > 0 ? waitMs : null;
+	}
+
+	/**
+	 * Get best available provider from a list
+	 */
+	selectBestProvider(providers: string[]): string | null {
+		const available = providers.filter((p) => this.isAvailable(p));
+
+		if (available.length === 0) return null;
+
+		// Sort by remaining quota (prefer those with more remaining)
+		available.sort((a, b) => {
+			const signalA = this.getLatestSignal(a);
+			const signalB = this.getLatestSignal(b);
+			const remA = signalA?.remainingPct ?? 100;
+			const remB = signalB?.remainingPct ?? 100;
+			return remB - remA;
+		});
+
+		return available[0];
+	}
+
+	/**
+	 * Clear stale signals
+	 */
+	clearStale(): void {
+		const cutoff = Date.now() - this.staleThresholdMs;
+
+		for (const entry of Array.from(this.signals.entries())) {
+			const [key, sigs] = entry;
+			const fresh = sigs.filter(
+				(s: QuotaSignal) => Date.parse(s.capturedAt) >= cutoff,
+			);
+			if (fresh.length === 0) {
+				this.signals.delete(key);
+			} else {
+				this.signals.set(key, fresh);
+			}
+		}
+	}
+
+	/**
+	 * Generate quota report
+	 */
+	generateReport(providers: string[]): string {
+		const lines = ["Quota Status Report", "=".repeat(40), ""];
+
+		for (const provider of providers) {
+			const state = this.getProviderState(provider);
+			const latest = this.getLatestSignal(provider);
+
+			const status = state.exhausted
+				? "EXHAUSTED"
+				: state.limited
+					? "LIMITED"
+					: "AVAILABLE";
+
+			lines.push(`${provider}: ${status}`);
+
+			if (latest) {
+				lines.push(`  Latest: ${latest.usedPct ?? 0}% used`);
+				if (latest.resetsAt) {
+					const wait = Date.parse(latest.resetsAt) - Date.now();
+					if (wait > 0) {
+						lines.push(`  Resets: in ${Math.ceil(wait / 60000)} minutes`);
+					}
+				}
+				lines.push(`  Source: ${latest.source}`);
+			}
+
+			lines.push("");
+		}
+
+		return lines.join("\n");
+	}
+}
+
+/**
+ * Parse quota signal from MiniMax error
+ */
+export function parseMiniMaxError(error: unknown): QuotaSignal | null {
+	const e = error as Record<string, unknown>;
+	const msg = String(e.message ?? e.error ?? "");
+
+	// MiniMax quota error: "Error code: 2056 - Rate limit exceeded. Retry after..."
+	if (
+		msg.includes("2056") ||
+		msg.includes("quota") ||
+		msg.includes("rate limit")
+	) {
+		// Try to extract retry time
+		const retryMatch = msg.match(/retry after (\d+) (seconds?|minutes?)/i);
+		let retryAfterMs: number | undefined;
+
+		if (retryMatch) {
+			const value = parseInt(retryMatch[1], 10);
+			const unit = retryMatch[2].toLowerCase();
+			retryAfterMs = unit.startsWith("minute")
+				? value * 60 * 1000
+				: value * 1000;
+		}
+
+		return {
+			provider: "minimax",
+			windowType: "5h",
+			usedPct: 100,
+			remainingPct: 0,
+			exhausted: true,
+			source: "api_response",
+			capturedAt: new Date().toISOString(),
+			retryAfterMs,
+		};
+	}
+
+	return null;
+}
+
+/**
+ * Parse quota signal from OpenAI error
+ */
+export function parseOpenAIError(error: unknown): QuotaSignal | null {
+	const e = error as Record<string, unknown>;
+	const code = String(e.code ?? "");
+	const msg = String(e.message ?? e.error ?? "");
+
+	if (code === "insufficient_quota" || code === "context_length_exceeded") {
+		return {
+			provider: "openai",
+			windowType: "daily",
+			usedPct: 100,
+			remainingPct: 0,
+			exhausted: true,
+			source: "api_response",
+			capturedAt: new Date().toISOString(),
+		};
+	}
+
+	if (msg.includes("429")) {
+		const retryMatch = msg.match(/retry after (\d+) (seconds?|minutes?)/i);
+		let retryAfterMs: number | undefined;
+
+		if (retryMatch) {
+			const value = parseInt(retryMatch[1], 10);
+			const unit = retryMatch[2].toLowerCase();
+			retryAfterMs = unit.startsWith("minute")
+				? value * 60 * 1000
+				: value * 1000;
+		}
+
+		return {
+			provider: "openai",
+			windowType: "5h",
+			usedPct: 100,
+			remainingPct: 0,
+			exhausted: true,
+			source: "api_response",
+			capturedAt: new Date().toISOString(),
+			retryAfterMs,
+		};
+	}
+
+	return null;
+}

package/packages/quota-manager/src/tui-usage-monitor.ts

@@ -0,0 +1,355 @@
+/**
+ * TUI Usage Monitor — Unified TUI Message Parser
+ *
+ * Hooks into pi's TUI messages to capture quota signals from all providers.
+ * Handles OpenAI, GLM, and any other provider that reports via TUI.
+ *
+ * Usage:
+ * ```typescript
+ * const monitor = new TUIUsageMonitor(quotaManager);
+ *
+ * // Hook into pi
+ * pi.on("error", (event) => monitor.processMessage(event.message));
+ * pi.on("message", (event) => monitor.processMessage(event.message));
+ * ```
+ */
+
+import { EventEmitter } from "node:events";
+import type { QuotaManager } from "./quota-manager.js";
+
+export interface TUIUsageSignal {
+	provider: "openai" | "glm" | "anthropic" | "openrouter" | "unknown";
+	timestamp: string;
+	/** Usage percentage (0-100), if available */
+	usedPct?: number;
+	/** Remaining percentage (0-100) */
+	remainingPct: number;
+	/** If exhausted */
+	exhausted: boolean;
+	/** Reset time */
+	resetsAt?: string;
+	/** Which limit was hit */
+	limitType: "tokens" | "context_window" | "rate_limit" | "unknown";
+	/** Original message */
+	originalMessage: string;
+}
+
+export interface TUIUsageMonitorConfig {
+	/** QuotaManager instance to feed signals into */
+	quotaManager: QuotaManager;
+	/** Enable debug logging */
+	debug?: boolean;
+}
+
+/**
+ * Provider-specific patterns
+ */
+const PROVIDER_PATTERNS = {
+	openai: [
+		/(?:^|\s)OpenAI(?:$|\s)/i,
+		/(?:^|\s)GPT(?:$|\s)/i,
+		/openai.*(?:quota|limit|exhausted)/i,
+		/gpt.*(?:quota|limit|exhausted)/i,
+		/insufficient_quota/i,
+		/context_length_exceeded/i,
+		/openai.*rate.?limit/i,
+		/429.*openai/i,
+		/openai.*context.*(?:window|length)/i,
+	],
+	glm: [
+		/(?:^|\s)GLM(?:$|\s)/i,
+		/(?:^|\s)Zhipu(?:$|\s)/i,
+		/glm.*(?:quota|limit|exhausted)/i,
+		/zhipu.*(?:quota|limit|exhausted)/i,
+		/glm.*context.*(?:window|length)/i,
+		/glm.*rate.?limit/i,
+	],
+	anthropic: [
+		/(?:^|\s)Claude(?:$|\s)/i,
+		/(?:^|\s)Anthropic(?:$|\s)/i,
+		/anthropic.*(?:quota|limit|exhausted)/i,
+		/claude.*(?:quota|limit|exhausted)/i,
+		/overloaded_error/i,
+		/rate_limit_error/i,
+	],
+	openrouter: [
+		/(?:^|\s)OpenRouter(?:$|\s)/i,
+		/openrouter.*(?:quota|limit|exhausted)/i,
+	],
+};
+
+const RESET_TIME_PATTERNS = [
+	/reset(?:s)?\s+(?:at|in)\s+(\d{1,2}):(\d{2})/i,
+	/(?:at|in)\s+(\d{1,2}):(\d{2})/i,
+	/retry\s+after\s+(\d{1,2}):(\d{2})/i,
+	/(\d{1,2}):(\d{2})\s*(?:am|pm)/i,
+];
+
+const PERCENTAGE_PATTERN = /(\d+)%/;
+
+export class TUIUsageMonitor extends EventEmitter {
+	private readonly quotaManager: QuotaManager;
+	private readonly debug: boolean;
+	private lastSignals: Map<string, TUIUsageSignal> = new Map();
+
+	constructor(config: TUIUsageMonitorConfig) {
+		super();
+		this.quotaManager = config.quotaManager;
+		this.debug = config.debug ?? false;
+	}
+
+	/**
+	 * Process a TUI message and extract quota signals
+	 */
+	processMessage(message: string): TUIUsageSignal | null {
+		// Try to identify provider
+		const provider = this.detectProvider(message);
+		if (!provider) {
+			return null;
+		}
+
+		// Parse the signal
+		const signal = this.parseSignal(message, provider);
+		if (!signal) {
+			return null;
+		}
+
+		// Store last signal
+		this.lastSignals.set(provider, signal);
+
+		// Record to QuotaManager
+		this.recordToQuotaManager(signal);
+
+		// Emit event
+		this.emit("signal", signal);
+
+		// Debug log
+		if (this.debug) {
+			console.log(`[TUIUsageMonitor] Detected ${provider}:`, signal);
+		}
+
+		return signal;
+	}
+
+	/**
+	 * Detect which provider the message is about
+	 */
+	detectProvider(
+		message: string,
+	): "openai" | "glm" | "anthropic" | "openrouter" | null {
+		for (const [provider, patterns] of Object.entries(PROVIDER_PATTERNS)) {
+			for (const pattern of patterns) {
+				if (pattern.test(message)) {
+					return provider as "openai" | "glm" | "anthropic" | "openrouter";
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Get the last signal for a provider
+	 */
+	getLastSignal(
+		provider: "openai" | "glm" | "anthropic" | "openrouter",
+	): TUIUsageSignal | null {
+		return this.lastSignals.get(provider) ?? null;
+	}
+
+	/**
+	 * Get all last signals
+	 */
+	getAllLastSignals(): Map<string, TUIUsageSignal> {
+		return new Map(this.lastSignals);
+	}
+
+	/**
+	 * Clear stored signals
+	 */
+	clear(): void {
+		this.lastSignals.clear();
+	}
+
+	/**
+	 * Parse the quota signal from message
+	 */
+	private parseSignal(
+		message: string,
+		provider: "openai" | "glm" | "anthropic" | "openrouter",
+	): TUIUsageSignal | null {
+		// Determine limit type
+		const limitType = this.detectLimitType(message);
+
+		// Parse reset time
+		const resetsAt = this.parseResetTime(message);
+
+		// Parse percentage if available
+		const pctMatch = message.match(PERCENTAGE_PATTERN);
+		const usedPct = pctMatch ? parseInt(pctMatch[1], 10) : undefined;
+
+		// Determine if exhausted
+		const exhausted =
+			usedPct !== undefined
+				? usedPct >= 100
+				: this.containsExhaustedKeywords(message);
+
+		if (!exhausted && !resetsAt) {
+			// Not a quota signal
+			return null;
+		}
+
+		return {
+			provider,
+			timestamp: new Date().toISOString(),
+			usedPct,
+			remainingPct: usedPct !== undefined ? 100 - usedPct : 0,
+			exhausted,
+			resetsAt,
+			limitType,
+			originalMessage: message,
+		};
+	}
+
+	/**
+	 * Detect the type of limit that was hit
+	 */
+	private detectLimitType(
+		message: string,
+	): "tokens" | "context_window" | "rate_limit" | "unknown" {
+		const lowerMsg = message.toLowerCase();
+
+		// Context window
+		if (
+			lowerMsg.includes("context") &&
+			(lowerMsg.includes("window") ||
+				lowerMsg.includes("length") ||
+				lowerMsg.includes("full") ||
+				lowerMsg.includes("exceeded"))
+		) {
+			return "context_window";
+		}
+
+		// Rate limit
+		if (
+			lowerMsg.includes("rate") ||
+			lowerMsg.includes("429") ||
+			lowerMsg.includes("too many requests")
+		) {
+			return "rate_limit";
+		}
+
+		// Tokens/quota exhausted
+		if (
+			lowerMsg.includes("quota") ||
+			lowerMsg.includes("exhausted") ||
+			lowerMsg.includes("ran out") ||
+			lowerMsg.includes("limit")
+		) {
+			return "tokens";
+		}
+
+		return "unknown";
+	}
+
+	/**
+	 * Check if message contains exhausted keywords
+	 */
+	private containsExhaustedKeywords(message: string): boolean {
+		const keywords = [
+			"exhausted",
+			"quota",
+			"limit",
+			"rate limit",
+			"429",
+			"exceeded",
+			"ran out",
+		];
+		const lowerMsg = message.toLowerCase();
+		return keywords.some((kw) => lowerMsg.includes(kw));
+	}
+
+	/**
+	 * Parse reset time from message
+	 */
+	private parseResetTime(message: string): string | undefined {
+		for (const pattern of RESET_TIME_PATTERNS) {
+			const match = message.match(pattern);
+			if (match) {
+				let hour = parseInt(match[1], 10);
+				const minute = parseInt(match[2], 10);
+
+				// Handle AM/PM
+				const matchIndex = message.indexOf(match[0]);
+				const afterMatch = message.slice(matchIndex, matchIndex + 20);
+				const isPM = /pm/i.test(afterMatch);
+				const isAM = /am/i.test(afterMatch);
+
+				if (isPM && hour < 12) hour += 12;
+				if (isAM && hour === 12) hour = 0;
+
+				// Convert to ISO string
+				const now = new Date();
+				const resetTime = new Date(now);
+				resetTime.setHours(hour, minute, 0, 0);
+
+				// If time has passed today, assume tomorrow
+				if (resetTime <= now) {
+					resetTime.setDate(resetTime.getDate() + 1);
+				}
+
+				return resetTime.toISOString();
+			}
+		}
+		return undefined;
+	}
+
+	/**
+	 * Record signal to QuotaManager
+	 */
+	private recordToQuotaManager(signal: TUIUsageSignal): void {
+		// Map limit type to window type
+		let windowType: "5h" | "daily" | "weekly" | "monthly" = "5h";
+
+		if (signal.limitType === "context_window") {
+			// Context window is usually daily or 5h depending on provider
+			windowType = "daily";
+		}
+
+		// Record to QuotaManager
+		this.quotaManager.recordSignal({
+			provider: signal.provider,
+			source: "tui_message",
+			windowType,
+			usedPct: signal.usedPct,
+			exhausted: signal.exhausted,
+			resetsAt: signal.resetsAt,
+		});
+	}
+}
+
+/**
+ * Create a TUI usage monitor and automatically hook into pi
+ */
+export function createTUIUsageMonitor(
+	quotaManager: QuotaManager,
+	pi: {
+		on: (event: string, handler: (event: { message: string }) => void) => void;
+	},
+	config?: { debug?: boolean },
+): TUIUsageMonitor {
+	const monitor = new TUIUsageMonitor({
+		quotaManager,
+		debug: config?.debug,
+	});
+
+	// Hook into pi events
+	pi.on("error", (event: { message: string }) => {
+		monitor.processMessage(event.message);
+	});
+
+	pi.on("message", (event: { message: string }) => {
+		monitor.processMessage(event.message);
+	});
+
+	return monitor;
+}