@ai-devkit/agent-manager 0.28.0 → 0.29.0

package/src/__tests__/capacity/codex.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  CODEX_APP_SERVER_ARGS,
+  parseUsage,
+  probeCodexCapacity,
+  resolveCodexAuthPath,
+  toRateWindow
+} from '../../capacity/codex.js';
+
+const checkedAt = '2026-08-20T10:00:00.000Z';
+const context = { installed: true, checkedAt };
+
+function apiUsage(overrides: Record<string, unknown> = {}) {
+  return {
+    rate_limit: {
+      primary_window: { used_percent: 20, limit_window_seconds: 18_000, reset_at: 1_787_220_000 },
+      secondary_window: { used_percent: 60, limit_window_seconds: 604_800, reset_at: 1_787_824_800 },
+      ...overrides
+    },
+    credits: { balance: 12.5 },
+    additional_rate_limits: [{
+      limit_name: 'reviews',
+      rate_limit: {
+        primary_window: { used_percent: 10, limit_window_seconds: 3_600, reset_at: 1_787_220_000 }
+      }
+    }]
+  };
+}
+
+describe('Codex auth resolution', () => {
+  it('uses CODEX_HOME before HOME', () => {
+    expect(resolveCodexAuthPath({ CODEX_HOME: '/custom/codex', HOME: '/users/test' })).toBe('/custom/codex/auth.json');
+  });
+
+  it('falls back to ~/.codex/auth.json', () => {
+    expect(resolveCodexAuthPath({ HOME: '/users/test' })).toBe('/users/test/.codex/auth.json');
+  });
+});
+
+describe('Codex API usage mapping', () => {
+  it('converts an API window without treating missing data as zero', () => {
+    expect(toRateWindow({ used_percent: 25, limit_window_seconds: 18_000, reset_at: 1_787_220_000 }, 'session', 'Session')).toEqual({
+      id: 'session', label: 'Session', durationMinutes: 300, usedPercent: 25,
+      resetsAt: '2026-08-20T10:00:00.000Z'
+    });
+    expect(toRateWindow({}, 'session', 'Session')).toMatchObject({ usedPercent: null });
+  });
+
+  it('maps session, weekly, credits, and extra limits', () => {
+    const snapshot = parseUsage(apiUsage(), 'pat');
+    expect(snapshot).toMatchObject({ source: 'pat', creditsRemaining: 12.5 });
+    expect(snapshot.windows).toEqual([
+      expect.objectContaining({ id: 'session', durationMinutes: 300 }),
+      expect.objectContaining({ id: 'weekly', durationMinutes: 10080 }),
+      expect.objectContaining({ id: 'reviews:primary', durationMinutes: 60 })
+    ]);
+  });
+
+  it('represents missing limits as unavailable rather than zero', () => {
+    const snapshot = parseUsage({ credits: {} }, 'oauth');
+    expect(snapshot.windows).toEqual([]);
+    expect(snapshot.creditsRemaining).toBeNull();
+  });
+});
+
+describe('tiered Codex probing', () => {
+  it('selects PAT, calls whoami then usage, and never invokes the CLI', async () => {
+    const fetch = vi.fn()
+      .mockResolvedValueOnce(new Response(JSON.stringify({ chatgpt_account_id: 'acct-1' }), { status: 200 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify(apiUsage()), { status: 200 }));
+    const rpc = vi.fn();
+    const result = await probeCodexCapacity({
+      ...context, readFile: async () => JSON.stringify({
+        personal_access_token: 'pat-secret',
+        tokens: { access_token: 'ignored-oauth', account_id: 'ignored-account' }
+      }), fetch, rpc
+    });
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(fetch.mock.calls[0][0]).toBe('https://auth.openai.com/api/accounts/v1/user-auth-credential/whoami');
+    expect(fetch.mock.calls[1][0]).toBe('https://chatgpt.com/backend-api/wham/usage');
+    expect(fetch.mock.calls[1][1].headers).toMatchObject({ Authorization: 'Bearer pat-secret', 'ChatGPT-Account-Id': 'acct-1' });
+    expect(rpc).not.toHaveBeenCalled();
+    expect(result).toMatchObject({ provider: 'codex', available: 'yes', creditsRemaining: 12.5, authenticated: true });
+    expect(result.windows.map(window => window.id)).toEqual(['session', 'weekly', 'reviews:primary']);
+  });
+
+  it('selects a fresh OAuth token without calling whoami', async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(apiUsage()), { status: 200 }));
+    const result = await probeCodexCapacity({
+      ...context,
+      readFile: async () => JSON.stringify({ tokens: { access_token: 'oauth-secret', account_id: 'acct-2', expires_at: 1_800_000_000 } }),
+      fetch,
+      now: () => new Date('2026-08-20T10:00:00.000Z')
+    });
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(fetch.mock.calls[0][1].headers).toMatchObject({ Authorization: 'Bearer oauth-secret', 'ChatGPT-Account-Id': 'acct-2' });
+    expect(result.available).toBe('yes');
+  });
+
+  it.each([
+    ['missing auth file', async () => { throw Object.assign(new Error('missing'), { code: 'ENOENT' }); }],
+    ['stale OAuth token', async () => JSON.stringify({ tokens: { access_token: 'stale-secret', account_id: 'acct', expires_at: 1 } })],
+    ['OAuth 401', async () => JSON.stringify({ tokens: { access_token: 'oauth-secret', account_id: 'acct', expires_at: 1_800_000_000 } })]
+  ])('falls back to the CLI for %s', async (name, readFile) => {
+    const fetch = vi.fn().mockResolvedValue(new Response('', { status: name === 'OAuth 401' ? 401 : 200 }));
+    const rpc = vi.fn(async () => ({
+      rateLimits: { rateLimits: { primary: { usedPercent: 5, windowDurationMins: 300, resetsAt: null } } },
+      account: { account: { type: 'chatgpt' } }
+    }));
+    const result = await probeCodexCapacity({ ...context, readFile, fetch, rpc, now: () => new Date(checkedAt) });
+    expect(rpc).toHaveBeenCalledOnce();
+    expect(result.windows).toHaveLength(1);
+  });
+
+  it('falls back to CLI if PAT requests fail', async () => {
+    const rpc = vi.fn(async () => ({ rateLimits: {}, account: { account: null } }));
+    const result = await probeCodexCapacity({
+      ...context,
+      readFile: async () => JSON.stringify({ personal_access_token: 'pat-secret' }),
+      fetch: vi.fn().mockRejectedValue(new Error('network failure pat-secret')),
+      rpc
+    });
+    expect(rpc).toHaveBeenCalledOnce();
+    expect(result.available).toBe('unknown');
+  });
+
+  it('tries fresh OAuth after a PAT request fails', async () => {
+    const fetch = vi.fn()
+      .mockRejectedValueOnce(new Error('PAT failed'))
+      .mockResolvedValueOnce(new Response(JSON.stringify(apiUsage()), { status: 200 }));
+    const rpc = vi.fn();
+    const result = await probeCodexCapacity({
+      ...context,
+      readFile: async () => JSON.stringify({
+        personal_access_token: 'pat-secret',
+        tokens: { access_token: 'oauth-secret', account_id: 'acct', expires_at: 1_800_000_000 }
+      }),
+      fetch,
+      rpc,
+      now: () => new Date(checkedAt)
+    });
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(result.available).toBe('yes');
+    expect(rpc).not.toHaveBeenCalled();
+  });
+
+  it('uses hardened read-only app-server arguments and both account methods', async () => {
+    const rpc = vi.fn(async () => ({
+      rateLimits: { rateLimits: { primary: { usedPercent: 5, windowDurationMins: 300, resetsAt: null } } },
+      account: { account: { type: 'chatgpt' } }
+    }));
+    await probeCodexCapacity({ ...context, readFile: async () => '{}', rpc });
+    const messages = rpc.mock.calls[0][0];
+    expect(messages.map(message => message.method)).toEqual([
+      'initialize', 'initialized', 'account/rateLimits/read', 'account/read'
+    ]);
+    expect(JSON.stringify(messages)).not.toMatch(/prompt|turn\/start/);
+    expect(CODEX_APP_SERVER_ARGS).toEqual(['-s', 'read-only', '-a', 'untrusted', 'app-server']);
+  });
+
+  it('uses account/read to distinguish logged-out CLI state', async () => {
+    const result = await probeCodexCapacity({
+      ...context,
+      readFile: async () => '{}',
+      rpc: async () => ({ rateLimits: {}, account: { account: null } })
+    });
+    expect(result).toMatchObject({ authenticated: false, available: 'unknown' });
+  });
+
+  it('never exposes tokens or raw auth content through failures', async () => {
+    const secrets = ['pat-secret-value', 'oauth-secret-value', 'refresh-secret-value'];
+    const result = await probeCodexCapacity({
+      ...context,
+      readFile: async () => JSON.stringify({
+        personal_access_token: secrets[0],
+        tokens: { access_token: secrets[1], refresh_token: secrets[2] }
+      }),
+      fetch: vi.fn().mockRejectedValue(new Error(secrets.join(' '))),
+      rpc: async () => { throw new Error(secrets.join(' ')); }
+    });
+    const output = JSON.stringify(result);
+    for (const secret of secrets) expect(output).not.toContain(secret);
+  });
+});

package/src/__tests__/capacity/index.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getCodexCapacityReport } from '../../capacity/index.js';
+
+const checkedAt = '2026-08-09T10:00:00.000Z';
+
+describe('getCodexCapacityReport', () => {
+  it('checks Codex installation before probing', async () => {
+    const probe = vi.fn(async context => ({
+      provider: 'codex', generatedAt: context.checkedAt,
+      authenticated: true, available: 'yes' as const, windows: [], creditsRemaining: null
+    }));
+
+    const report = await getCodexCapacityReport({
+      now: () => new Date(checkedAt),
+      path: '/usr/bin:/opt/bin',
+      access: async target => {
+        if (target !== '/opt/bin/codex') throw new Error('missing');
+      },
+      probe
+    });
+
+    expect(probe).toHaveBeenCalledWith({ installed: true, checkedAt });
+    expect(report).toMatchObject({ provider: 'codex', generatedAt: checkedAt, available: 'yes' });
+  });
+
+  it('redacts unexpected probe failures into a stable unknown result', async () => {
+    const report = await getCodexCapacityReport({
+      now: () => new Date(checkedAt),
+      path: '',
+      probe: async () => { throw new Error('private provider response'); }
+    });
+
+    expect(report).toMatchObject({
+      provider: 'codex', available: 'unknown', authenticated: null, windows: []
+    });
+    expect(JSON.stringify(report)).not.toContain('private provider response');
+  });
+});

package/src/__tests__/print/ClaudePrintAgent.integration.test.ts

@@ -8,6 +8,7 @@ import {
     ClaudePrintAgentService,
     ClaudePrintRunner,
     DurableAgentRepository,
+    type ProcessInspector,
 } from '../../index.js';
 
 const roots: string[] = [];
@@ -28,11 +29,17 @@ describe('Claude durable-agent fake-provider journey', () => {
         const capture = path.join(root, 'capture.jsonl');
         process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE = capture;
         const executable = fileURLToPath(new URL('../fixtures/fake-claude.cjs', import.meta.url));
-        const repository = new DurableAgentRepository({ dbPath: path.join(root, 'state', 'agents.db') });
+        const processInspector: ProcessInspector = {
+            getIdentity: (pid) => ({ pid, startedAt: `process-${pid}` }),
+        };
+        const repository = new DurableAgentRepository({
+            dbPath: path.join(root, 'state', 'agents.db'),
+            processInspector,
+        });
         const service = new ClaudePrintAgentService({
             repository,
             probe: new ClaudeCliProbe({ executable }),
-            runner: new ClaudePrintRunner(),
+            runner: new ClaudePrintRunner({ processInspector }),
             executable,
         });
 

package/src/capacity/codex.ts

@@ -0,0 +1,320 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { CapacityReport, CapacityWindow } from './types.js';
+
+type CodexUsageSource = 'pat' | 'oauth' | 'cli';
+type UsageSnapshot = { windows: CapacityWindow[]; creditsRemaining: number | null; source: CodexUsageSource };
+
+type UnknownRecord = Record<string, unknown>;
+type RpcMessage = { id?: number; method: string; params?: UnknownRecord };
+type CliResponses = { rateLimits: unknown; account: unknown };
+type CodexRpc = (messages: RpcMessage[]) => Promise<CliResponses>;
+
+export const CODEX_APP_SERVER_ARGS = ['-s', 'read-only', '-a', 'untrusted', 'app-server'] as const;
+
+type CodexProbeOptions = {
+  installed: boolean;
+  checkedAt: string;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+  fetch?: typeof globalThis.fetch;
+  rpc?: CodexRpc;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  now?: () => Date;
+};
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as UnknownRecord
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function resetTime(value: unknown): string | null {
+  const seconds = finiteNumber(value);
+  if (seconds !== null) return new Date(seconds * 1000).toISOString();
+  if (typeof value === 'string' && !Number.isNaN(Date.parse(value))) return new Date(value).toISOString();
+  return null;
+}
+
+function safeIdentifier(value: unknown): string | null {
+  const candidate = nonEmptyText(value);
+  if (!candidate || !/^[a-z][a-z0-9_-]{0,63}$/i.test(candidate)) return null;
+  if (/(?:account|token|secret|key)[_-]?\d{6,}/i.test(candidate)) return null;
+  return candidate;
+}
+
+export function resolveCodexAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  const root = env.CODEX_HOME || join(env.HOME || '', '.codex');
+  return join(root, 'auth.json');
+}
+
+export function toRateWindow(
+  value: unknown,
+  id: string,
+  label: string
+): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  const used = finiteNumber(input.used_percent);
+  const seconds = finiteNumber(input.limit_window_seconds);
+  return {
+    id,
+    label,
+    durationMinutes: seconds === null ? null : seconds / 60,
+    usedPercent: used,
+    resetsAt: resetTime(input.reset_at)
+  };
+}
+
+function extraWindows(value: unknown): CapacityWindow[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry, index) => {
+    const limit = record(entry);
+    if (!limit) return [];
+    const scope = safeIdentifier(limit.limit_name) ?? `extra-${index + 1}`;
+    const windows = record(limit.rate_limit) ?? limit;
+    return [
+      toRateWindow(windows.primary_window, `${scope}:primary`, `${scope} primary`),
+      toRateWindow(windows.secondary_window, `${scope}:secondary`, `${scope} secondary`)
+    ].filter((window): window is CapacityWindow => window !== null);
+  });
+}
+
+export function parseUsage(raw: unknown, source: 'pat' | 'oauth'): UsageSnapshot {
+  const response = record(raw) ?? {};
+  const limits = record(response.rate_limit) ?? {};
+  const credits = record(response.credits) ?? {};
+  return {
+    windows: [
+      toRateWindow(limits.primary_window, 'session', 'Session'),
+      toRateWindow(limits.secondary_window, 'weekly', 'Weekly'),
+      ...extraWindows(response.additional_rate_limits)
+    ].filter((window): window is CapacityWindow => window !== null),
+    creditsRemaining: finiteNumber(credits.balance),
+    source
+  };
+}
+
+function cliWindow(value: unknown, id: string, label: string): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  return {
+    id,
+    label,
+    durationMinutes: finiteNumber(input.windowDurationMins),
+    usedPercent: finiteNumber(input.usedPercent),
+    resetsAt: resetTime(input.resetsAt)
+  };
+}
+
+function cliSnapshotWindows(value: unknown, fallbackId: string): CapacityWindow[] {
+  const snapshot = record(value);
+  if (!snapshot) return [];
+  const scope = safeIdentifier(snapshot.limitId) ?? safeIdentifier(fallbackId) ?? 'codex';
+  return [
+    cliWindow(snapshot.primary, `${scope}:primary`, `${scope} primary`),
+    cliWindow(snapshot.secondary, `${scope}:secondary`, `${scope} secondary`)
+  ].filter((item): item is CapacityWindow => item !== null);
+}
+
+export function parseCliUsage(raw: unknown): UsageSnapshot {
+  const response = record(raw) ?? {};
+  const primary = record(response.rateLimits);
+  const windows = primary ? cliSnapshotWindows(primary, 'codex') : [];
+  const buckets = record(response.rateLimitsByLimitId);
+  if (buckets) {
+    for (const [id, snapshot] of Object.entries(buckets)) windows.push(...cliSnapshotWindows(snapshot, id));
+  }
+  const unique = [...new Map(windows.map(window => [window.id, window])).values()];
+  return { windows: unique, creditsRemaining: null, source: 'cli' };
+}
+
+function capacityFromSnapshot(snapshot: UsageSnapshot, context: CodexProbeOptions, raw?: unknown): CapacityReport {
+  const hasUsage = snapshot.windows.some(window => window.usedPercent !== null);
+  const rateLimits = record(record(raw)?.rateLimits);
+  const reached = nonEmptyText(rateLimits?.rateLimitReachedType);
+  const resetCredits = record(record(raw)?.rateLimitResetCredits) ?? record(record(raw)?.usageLimitResetCredits);
+  return {
+    provider: 'codex',
+    generatedAt: context.checkedAt,
+    authenticated: true,
+    available: reached ? 'no' : hasUsage ? 'yes' : 'unknown',
+    windows: snapshot.windows,
+    creditsRemaining: snapshot.creditsRemaining ?? finiteNumber(resetCredits?.availableCount)
+  };
+}
+
+function jwtExpiry(token: string): number | null {
+  const part = token.split('.')[1];
+  if (!part) return null;
+  try {
+    return finiteNumber(record(JSON.parse(Buffer.from(part, 'base64url').toString('utf8')))?.exp);
+  } catch {
+    return null;
+  }
+}
+
+function staleOAuth(tokens: UnknownRecord, token: string, now: Date): boolean {
+  const metadata = tokens.expires_at ?? tokens.expiresAt ?? tokens.expiry;
+  let expiry: number | null = finiteNumber(metadata);
+  if (typeof metadata === 'string') {
+    const parsed = Date.parse(metadata);
+    expiry = Number.isNaN(parsed) ? null : parsed / 1000;
+  }
+  expiry ??= jwtExpiry(token);
+  return expiry !== null && expiry <= now.getTime() / 1000;
+}
+
+async function fetchJson(fetcher: typeof globalThis.fetch, url: string, init: RequestInit, timeoutMs: number): Promise<unknown> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetcher(url, { ...init, signal: controller.signal });
+    if (!response.ok) throw new Error(response.status === 401 ? 'unauthorized' : 'request failed');
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function apiSnapshot(
+  token: string,
+  accountId: string,
+  source: 'pat' | 'oauth',
+  options: CodexProbeOptions
+): Promise<UsageSnapshot> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const raw = await fetchJson(fetcher, 'https://chatgpt.com/backend-api/wham/usage', {
+    headers: { Authorization: `Bearer ${token}`, 'ChatGPT-Account-Id': accountId }
+  }, options.timeoutMs ?? 5000);
+  return parseUsage(raw, source);
+}
+
+function appServerRpc(messages: RpcMessage[], timeoutMs = 5000): Promise<CliResponses> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('codex', CODEX_APP_SERVER_ARGS, {
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    const results: Partial<CliResponses> = {};
+    let buffer = '';
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      if (error) reject(error);
+      else resolve(results as CliResponses);
+    };
+    const timer = setTimeout(() => finish(new Error('codex probe timed out')), timeoutMs);
+    child.once('error', () => finish(new Error('codex app-server unavailable')));
+    child.once('exit', () => { if (!settled) finish(new Error('codex app-server exited')); });
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      buffer += chunk;
+      for (;;) {
+        const newline = buffer.indexOf('\n');
+        if (newline < 0) break;
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (!line) continue;
+        let message: UnknownRecord;
+        try { message = JSON.parse(line) as UnknownRecord; } catch { continue; }
+        if (message.id === 1) {
+          for (const request of messages.slice(1)) child.stdin.write(`${JSON.stringify(request)}\n`);
+        } else if (message.id === 2) {
+          if (message.error) finish(new Error('codex rate-limit method failed'));
+          else results.rateLimits = message.result;
+        } else if (message.id === 3) {
+          if (message.error) finish(new Error('codex account method failed'));
+          else results.account = message.result;
+        }
+        if ('rateLimits' in results && 'account' in results) finish();
+      }
+    });
+    child.stdin.write(`${JSON.stringify(messages[0])}\n`);
+  });
+}
+
+function unavailable(options: CodexProbeOptions): CapacityReport {
+  return {
+    provider: 'codex',
+    generatedAt: options.checkedAt,
+    authenticated: null,
+    available: 'unknown',
+    windows: [],
+    creditsRemaining: null
+  };
+}
+
+async function cliFallback(options: CodexProbeOptions): Promise<CapacityReport> {
+  if (!options.installed) return unavailable(options);
+  const messages: RpcMessage[] = [
+    { id: 1, method: 'initialize', params: {
+      clientInfo: { name: 'ai-devkit', title: null, version: '1' }, capabilities: null
+    } },
+    { method: 'initialized' },
+    { id: 2, method: 'account/rateLimits/read' },
+    { id: 3, method: 'account/read' }
+  ];
+  try {
+    const rpc = options.rpc ?? (requests => appServerRpc(requests, options.timeoutMs));
+    const response = await rpc(messages);
+    const result = capacityFromSnapshot(parseCliUsage(response.rateLimits), options, response.rateLimits);
+    const accountEnvelope = record(response.account);
+    if (accountEnvelope && Object.hasOwn(accountEnvelope, 'account') && !record(accountEnvelope.account)) {
+      result.authenticated = false;
+      result.available = 'unknown';
+    }
+    return result;
+  } catch {
+    return unavailable(options);
+  }
+}
+
+export async function probeCodexCapacity(options: CodexProbeOptions): Promise<CapacityReport> {
+  let parsed: UnknownRecord | null = null;
+  try {
+    const contents = await (options.readFile ?? readFile)(resolveCodexAuthPath(options.env), 'utf8');
+    parsed = record(JSON.parse(contents));
+  } catch {
+    return cliFallback(options);
+  }
+
+  const auth = parsed ?? {};
+  const pat = nonEmptyText(auth.personal_access_token);
+  if (pat) {
+    try {
+      const fetcher = options.fetch ?? globalThis.fetch;
+      const whoami = record(await fetchJson(fetcher,
+        'https://auth.openai.com/api/accounts/v1/user-auth-credential/whoami',
+        { headers: { Authorization: `Bearer ${pat}` } }, options.timeoutMs ?? 5000));
+      const accountId = nonEmptyText(whoami?.chatgpt_account_id);
+      if (!accountId) throw new Error('account unavailable');
+      return capacityFromSnapshot(await apiSnapshot(pat, accountId, 'pat', options), options);
+    } catch {
+      // Continue to a separately available OAuth credential before using the CLI.
+    }
+  }
+
+  const tokens = record(auth.tokens);
+  const accessToken = nonEmptyText(tokens?.access_token);
+  const accountId = nonEmptyText(tokens?.account_id);
+  if (tokens && accessToken && accountId && !staleOAuth(tokens, accessToken, (options.now ?? (() => new Date()))())) {
+    try {
+      return capacityFromSnapshot(await apiSnapshot(accessToken, accountId, 'oauth', options), options);
+    } catch {
+      return cliFallback(options);
+    }
+  }
+  return cliFallback(options);
+}

package/src/capacity/index.ts

@@ -0,0 +1,57 @@
+import { constants } from 'node:fs';
+import { access as fsAccess } from 'node:fs/promises';
+import path from 'node:path';
+import { probeCodexCapacity } from './codex.js';
+import type { CapacityReport } from './types.js';
+
+export type { CapacityReport, CapacityWindow } from './types.js';
+
+export type CapacityProbeOptions = {
+  now?: () => Date;
+  path?: string;
+  access?: (target: string) => Promise<void>;
+  probe?: typeof probeCodexCapacity;
+};
+
+async function canAccess(target: string, mode: number): Promise<boolean> {
+  try {
+    await fsAccess(target, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isCodexInstalled(pathValue: string, checkAccess?: (target: string) => Promise<void>): Promise<boolean> {
+  const directories = pathValue.split(path.delimiter).filter(Boolean);
+  for (const directory of directories) {
+    const executable = path.join(directory, 'codex');
+    if (checkAccess) {
+      try {
+        await checkAccess(executable);
+        return true;
+      } catch {
+        continue;
+      }
+    }
+    if (await canAccess(executable, constants.X_OK)) return true;
+  }
+  return false;
+}
+
+export async function getCodexCapacityReport(options: CapacityProbeOptions = {}): Promise<CapacityReport> {
+  const generatedAt = (options.now?.() ?? new Date()).toISOString();
+  const installed = await isCodexInstalled(options.path ?? process.env.PATH ?? '', options.access);
+  try {
+    return await (options.probe ?? probeCodexCapacity)({ installed, checkedAt: generatedAt });
+  } catch {
+    return {
+      provider: 'codex',
+      generatedAt,
+      authenticated: null,
+      available: 'unknown',
+      windows: [],
+      creditsRemaining: null
+    };
+  }
+}

package/src/capacity/types.ts

@@ -0,0 +1,18 @@
+export type Availability = 'yes' | 'no' | 'unknown';
+
+export interface CapacityWindow {
+  id: string;
+  label: string;
+  durationMinutes: number | null;
+  usedPercent: number | null;
+  resetsAt: string | null;
+}
+
+export interface CapacityReport {
+  provider: string;
+  generatedAt: string;
+  authenticated: boolean | null;
+  available: Availability;
+  windows: CapacityWindow[];
+  creditsRemaining: number | null;
+}

package/src/index.ts

@@ -1,4 +1,10 @@
 export { AgentManager, AgentNotRunningError } from './AgentManager.js';
+export { getCodexCapacityReport } from './capacity/index.js';
+export type {
+    CapacityProbeOptions,
+    CapacityReport,
+    CapacityWindow,
+} from './capacity/index.js';
 
 export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
 export { CodexAdapter } from './adapters/CodexAdapter.js';