@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/usage/limits/normalize.ts

@@ -0,0 +1,188 @@
+import type { UsageLimitsProvider, UsageProvider, UsageWindow } from '@adecore/agent-contracts';
+
+/* Everything a full read of a provider says about its plan, ready to be published as it is. */
+export interface ProviderReading {
+    plan: string | null;
+    windows: UsageWindow[];
+    cost: { sessionUsd: number } | null;
+}
+
+/* What a running turn reports in passing: a few windows, sometimes without their reset or duration. */
+export interface LimitsUpdate {
+    kind: UsageProvider;
+    // The account of the chat whose turn reported it; absent is the default account.
+    account?: string;
+    plan?: string | null;
+    windows: Partial<UsageWindow>[];
+}
+
+const MINUTE_MS = 60_000;
+const FIVE_HOURS_MS = 5 * 60 * MINUTE_MS;
+const WEEK_MS = 7 * 24 * 60 * MINUTE_MS;
+const MONTH_MS = 30 * 24 * 60 * MINUTE_MS;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function num(value: unknown): number | null {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function fraction(value: number): number {
+    return Math.min(1, Math.max(0, value));
+}
+
+/* A window is named after how long it lasts, never after the position it came in. */
+export function kindOfDuration(durationMs: number | null): UsageWindow['kind'] {
+    if (durationMs === null) {
+        return 'other';
+    }
+    if (durationMs >= MONTH_MS) {
+        return 'monthly';
+    }
+    if (durationMs >= WEEK_MS) {
+        return 'weekly';
+    }
+    return 'session';
+}
+
+const CLAUDE_WINDOWS: { key: string; id: string; label: string; kind: UsageWindow['kind']; durationMs: number }[] = [
+    { key: 'five_hour', id: 'five_hour', label: 'Session', kind: 'session', durationMs: FIVE_HOURS_MS },
+    { key: 'seven_day', id: 'seven_day', label: 'Weekly', kind: 'weekly', durationMs: WEEK_MS },
+    { key: 'seven_day_opus', id: 'seven_day_opus', label: 'Weekly · Opus', kind: 'weekly', durationMs: WEEK_MS },
+    { key: 'seven_day_sonnet', id: 'seven_day_sonnet', label: 'Weekly · Sonnet', kind: 'weekly', durationMs: WEEK_MS }
+];
+
+function slug(value: string): string {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+
+/*
+ * What `get_usage` answers. Claude reports a percent and an ISO moment there, while the event a
+ * running turn sends reports a fraction and epoch seconds; both are turned into a fraction and epoch
+ * milliseconds here, so nothing past this file has to remember which of the two it is holding.
+ */
+export function readClaudeUsage(response: unknown): ProviderReading | { unavailable: UsageLimitsProvider['unavailable'] } {
+    if (!isRecord(response)) {
+        return { unavailable: { reason: 'failed', message: 'Claude Code returned no readable usage' } };
+    }
+    const plan = typeof response.subscription_type === 'string' ? response.subscription_type : null;
+    const limits = isRecord(response.rate_limits) ? response.rate_limits : null;
+    if (response.rate_limits_available === false || limits === null) {
+        // An API key, Bedrock or Vertex account has no plan windows at all, which is not a failure.
+        return { unavailable: { reason: 'no-subscription', message: null } };
+    }
+    const windows: UsageWindow[] = [];
+    const push = (id: string, label: string, kind: UsageWindow['kind'], durationMs: number, entry: unknown): void => {
+        const window = isRecord(entry) ? entry : null;
+        const utilization = window === null ? null : num(window.utilization);
+        if (utilization === null) {
+            return;
+        }
+        const resetsAt = typeof window?.resets_at === 'string' ? Date.parse(window.resets_at) : Number.NaN;
+        windows.push({ id, label, kind, used: fraction(utilization / 100), resetsAt: Number.isNaN(resetsAt) ? null : resetsAt, durationMs });
+    };
+    for (const known of CLAUDE_WINDOWS) {
+        push(known.id, known.label, known.kind, known.durationMs, limits[known.key]);
+    }
+    for (const entry of Array.isArray(limits.model_scoped) ? limits.model_scoped : []) {
+        const name = isRecord(entry) && typeof entry.display_name === 'string' ? entry.display_name : null;
+        if (name !== null) {
+            push(`seven_day_${slug(name)}`, `Weekly · ${name}`, 'weekly', WEEK_MS, entry);
+        }
+    }
+    const session = isRecord(response.session) ? response.session : null;
+    const sessionUsd = session === null ? null : num(session.total_cost_usd);
+    return { plan, windows, cost: sessionUsd === null ? null : { sessionUsd } };
+}
+
+/* The `rate_limit_event` a turn streams: one window, a fraction, and seconds where the read had ISO. */
+export function readClaudeEvent(info: unknown): LimitsUpdate | null {
+    const event = isRecord(info) ? info : null;
+    const type = event !== null && typeof event.rateLimitType === 'string' ? event.rateLimitType : null;
+    const utilization = event === null ? null : num(event.utilization);
+    if (type === null || utilization === null) {
+        return null;
+    }
+    const known = CLAUDE_WINDOWS.find((window) => window.key === type);
+    const resetsAt = num(event?.resetsAt);
+    return {
+        kind: 'claude',
+        windows: [
+            {
+                id: known?.id ?? type,
+                ...(known ? { label: known.label, kind: known.kind, durationMs: known.durationMs } : {}),
+                used: fraction(utilization),
+                ...(resetsAt === null ? {} : { resetsAt: Math.round(resetsAt * 1000) })
+            }
+        ]
+    };
+}
+
+/*
+ * A Codex rate limit snapshot, from a read or from the notification a turn sends. Only the main
+ * allowance counts: the other ids are one model's own budget and read as a second plan.
+ */
+export function readCodexLimits(snapshot: unknown): ProviderReading | null {
+    const limits = isRecord(snapshot) ? snapshot : null;
+    if (limits === null || (typeof limits.limitId === 'string' && limits.limitId !== 'codex')) {
+        return null;
+    }
+    const plan = typeof limits.planType === 'string' ? limits.planType : null;
+    const windows: UsageWindow[] = [];
+    for (const [position, entry] of [
+        ['primary', limits.primary],
+        ['secondary', limits.secondary]
+    ] as const) {
+        const window = isRecord(entry) ? entry : null;
+        const usedPercent = window === null ? null : num(window.usedPercent);
+        if (usedPercent === null) {
+            continue;
+        }
+        const minutes = num(window?.windowDurationMins);
+        const durationMs = minutes === null ? null : Math.round(minutes * MINUTE_MS);
+        const kind = kindOfDuration(durationMs);
+        const resetsAt = num(window?.resetsAt);
+        windows.push({
+            id: position,
+            kind,
+            label: kind === 'session' ? 'Session' : kind === 'weekly' ? 'Weekly' : kind === 'monthly' ? 'Monthly' : 'Usage',
+            used: fraction(usedPercent / 100),
+            resetsAt: resetsAt === null ? null : Math.round(resetsAt * 1000),
+            durationMs
+        });
+    }
+    return { plan, windows, cost: null };
+}
+
+/*
+ * A sparse update folded onto what a full read drew. The row keeps its label, its reset and its
+ * length when the event leaves them out, which is what makes a mid-turn number land on the bar it
+ * belongs to instead of drawing a second one beside it.
+ */
+export function mergeWindows(known: readonly UsageWindow[], updates: readonly Partial<UsageWindow>[]): UsageWindow[] {
+    const merged = known.map((window) => ({ ...window }));
+    for (const update of updates) {
+        if (update.id === undefined || update.used === undefined) {
+            continue;
+        }
+        const at = merged.findIndex((window) => window.id === update.id);
+        if (at === -1) {
+            merged.push({
+                id: update.id,
+                kind: update.kind ?? 'other',
+                label: update.label ?? 'Usage',
+                used: update.used,
+                resetsAt: update.resetsAt ?? null,
+                durationMs: update.durationMs ?? null
+            });
+            continue;
+        }
+        merged[at] = { ...merged[at]!, ...update } as UsageWindow;
+    }
+    return merged;
+}

package/src/usage/limits/probe.ts

@@ -0,0 +1,120 @@
+import { withTimeout } from '../../async.ts';
+import type { UsageLimitsProvider } from '@adecore/agent-contracts';
+import { spawnChatProcess, type ChatProcess, type SpawnChatProcess } from '../../chat/chat-process.ts';
+import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo } from '../../chat/codex-transport.ts';
+import { readClaudeUsage, readCodexLimits, type ProviderReading } from './normalize.ts';
+import { errorText } from '../../error-text.ts';
+
+/* A CLI that has not answered by now is not going to; the next pass tries again. */
+const PROBE_TIMEOUT_MS = 20_000;
+const CODEX_READ_TIMEOUT_MS = 3_000;
+
+export type ProbeResult = ProviderReading | { unavailable: UsageLimitsProvider['unavailable'] };
+
+function failure(message: string): ProbeResult {
+    return { unavailable: { reason: 'failed', message } };
+}
+
+function timeoutOf<T>(work: Promise<T>, ms: number, what: string): Promise<T> {
+    return withTimeout(work, ms, `${what} did not answer in time`);
+}
+
+/*
+ * Asks Claude Code what is left of the plan, without a turn and without a token of our own. A
+ * `claude -p` on the stream-json protocol answers `get_usage` before any prompt, but only once it
+ * has been initialized: without that first control request the process waits and says nothing.
+ */
+export async function probeClaude(command: readonly string[], env: Record<string, string>, spawn: SpawnChatProcess = spawnChatProcess): Promise<ProbeResult> {
+    let child: ChatProcess;
+    try {
+        child = spawn({
+            command: [...command, '-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'],
+            cwd: process.cwd(),
+            env,
+            onExit: () => undefined
+        });
+    } catch (error) {
+        return failure(errorText(error));
+    }
+    const write = (frame: unknown): void => {
+        child.stdin.write(`${JSON.stringify(frame)}\n`);
+        child.stdin.flush();
+    };
+    const read = async (): Promise<ProbeResult> => {
+        write({ type: 'control_request', request_id: 'probe-init', request: { subtype: 'initialize', hooks: {} } });
+        let asked = false;
+        let buffer = '';
+        const decoder = new TextDecoder();
+        for await (const chunk of child.stdout as unknown as AsyncIterable<Uint8Array>) {
+            buffer += decoder.decode(chunk, { stream: true });
+            let at = buffer.indexOf('\n');
+            for (; at !== -1; at = buffer.indexOf('\n')) {
+                const line = buffer.slice(0, at);
+                buffer = buffer.slice(at + 1);
+                let frame: unknown;
+                try {
+                    frame = JSON.parse(line);
+                } catch {
+                    continue;
+                }
+                if (typeof frame !== 'object' || frame === null) {
+                    continue;
+                }
+                const envelope = frame as { type?: unknown; request_id?: unknown; response?: { subtype?: unknown; response?: unknown } };
+                if (envelope.type !== 'control_response') {
+                    continue;
+                }
+                if (!asked) {
+                    asked = true;
+                    write({ type: 'control_request', request_id: 'probe-usage', request: { subtype: 'get_usage' } });
+                    continue;
+                }
+                if (envelope.response?.subtype === 'error') {
+                    return failure('Claude Code refused to report its usage');
+                }
+                return readClaudeUsage(envelope.response?.response ?? envelope.response);
+            }
+        }
+        return failure('Claude Code closed without reporting its usage');
+    };
+
+    try {
+        return await timeoutOf(read(), PROBE_TIMEOUT_MS, 'Claude Code');
+    } catch (error) {
+        return failure(errorText(error));
+    } finally {
+        child.stdin.end();
+        child.kill('SIGTERM');
+    }
+}
+
+/* The same question to Codex: the app-server answers it over JSON-RPC right after the handshake. */
+export async function probeCodex(
+    command: readonly string[],
+    env: Record<string, string>,
+    client: CodexClientInfo = DEFAULT_CODEX_CLIENT
+): Promise<ProbeResult> {
+    let transport: CodexTransport | null = null;
+    try {
+        transport = new CodexTransport({
+            command: [...command],
+            cwd: process.cwd(),
+            env,
+            onFrame: () => undefined,
+            onExit: () => undefined
+        });
+        const open = transport;
+        await timeoutOf(open.request('initialize', { clientInfo: client, capabilities: { experimentalApi: true } }), PROBE_TIMEOUT_MS, 'Codex');
+        open.notify('initialized', {});
+        const answer = await timeoutOf(open.request('account/rateLimits/read', undefined), CODEX_READ_TIMEOUT_MS, 'Codex');
+        const snapshot = typeof answer === 'object' && answer !== null ? (answer as { rateLimits?: unknown }).rateLimits : null;
+        const reading = readCodexLimits(snapshot);
+        // An account on an API key has no plan windows; Codex answers, with nothing in it.
+        return reading ?? { unavailable: { reason: 'no-subscription', message: null } };
+    } catch (error) {
+        return failure(errorText(error));
+    } finally {
+        transport?.end();
+        transport?.kill();
+    }
+}